Metals Api

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds meaningful behavioral context: default model is free, Anthropic requires a BYO key passed via `_apiKey`, and calls are directed straight to Anthropic. This goes 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 four sentences, front-loaded with the core purpose. Every sentence adds value: main action, default model, key requirement, return format, and use cases. 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?

For a tool with 4 parameters and no output schema, the description covers the main behavior, return structure (per-model fields + combined view), score range (0-100), and appropriate use cases. It does not explain every output field but is sufficient for an agent to understand the tool's value.

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 reiterates that `_apiKey` is needed for Anthropic and that 'models' can be omitted for defaults, but does not add new semantic details beyond what the schema already 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 a specific verb ('Probe') and resource ('LLMs for what they know...score visibility 0-100 per model'), and distinguishes this tool from siblings like 'scan_competitor_ai_presence' and 'deep_research' by focusing on visibility scoring across models.

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

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

The description explicitly lists use cases: 'AI-marketing audits, pre-launch brand checks, competitive monitoring'. It does not mention when not to use or provide direct alternatives among siblings, but the context is clear enough for an agent to decide.

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

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

Annotations already indicate readOnlyHint, openWorldHint, idempotentHint, and non-destructive. Description adds that it is a single fast call, returns structured answers with stable citation URIs, and routes to the right sub-tool. This adds 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?

Description is front-loaded with the key instruction and includes examples, but is somewhat lengthy. However, every sentence serves a purpose: usage guidance, behavior, examples, and sibling differentiation. Could be slightly shorter but still effective.

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

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

Given the tool's complexity (4,774 tools, wide domain), the description is very complete: it explains when to use, what it does, expected output (structured answer with citations), and alternatives. No output schema but description compensates.

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 all 6 parameters describing the same natural language question. Description provides context that the tool accepts natural language questions and lists examples, which adds meaning beyond the schema's parameter descriptions.

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

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

Description clearly states the tool routes questions to a large set of verified sources and returns structured answers with citations. It distinguishes itself from siblings like ask_pipeworx_grounded and deep_research, and provides examples. The verb 'asks' and resource 'Pipeworx' are clearly defined.

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 'PREFER OVER WEB SEARCH' for specific data types, lists trigger phrases like 'what is', 'look up', and provides when-not-to-use guidance by naming alternatives. Also says 'START HERE for most questions', giving clear prioritization.

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

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

Adds significant behavioral context beyond annotations: hallucination resistance, extraction from tool result only, explicit refusal reasons, and cost of one extra LLM call. No contradiction with readOnlyHint, openWorldHint, idempotentHint, destructiveHint.

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

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

Well-structured with clear sections for return format and usage advice, but slightly verbose. Front-loaded with main purpose. Could be more concise while retaining 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?

Completely covers return format (with success and refusal objects), failure modes, and usage context. No output schema, so the description adequately explains return values and 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%, so baseline is 3. The description mentions aliases but does not add significant meaning beyond what is already in the schema's parameter descriptions. No additional usage details for the parameters.

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

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

The description clearly states the tool is a 'hallucination-resistant answer mode for high-stakes reads' and distinguishes it from sibling 'ask_pipeworx' by specifying it extracts answers only from tool results and returns explicit refusals, making the purpose highly specific and distinct.

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

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

Explicitly states when to use ('whenever an answer will be quoted, cited, or acted on') and when not to use ('prefer ask_pipeworx for casual lookups'), including the cost trade-off and example domains like financial verdicts and legal claims.

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 annotations (readOnly, idempotent) by detailing fan-out behavior, classifiers, response shapes, resolver contract, parent event extraction, news fallbacks, safety checks for low-confidence matches and closed markets, illiquid spreads, and resolution-rule risk. 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 core purpose and usage, but it is very verbose with extensive detail on internal mechanics. Every sentence adds value, but conciseness could be improved by moving some details to structured fields.

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, the description covers all essential aspects: input formats, internal processing, output structure, edge cases, safety mechanisms, and risk details. Without an output schema, it fully compensates by explaining return values and fields.

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

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

Schema coverage is 100% with descriptions for all three parameters. The description adds examples and context for market, depth, and include_raw but does not significantly extend semantics beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states the tool researches a Polymarket bet by pulling Pipeworx data, specifies inputs (slug, URL, question text), and lists concrete use cases. It distinguishes from siblings like polymarket_edges and polymarket_arbitrage by focusing on general research rather than specific edge 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 explicitly provides use cases ('Use for should I bet on X...') and advises inspecting resolver contract fields. However, it does not explicitly state when NOT to use the tool or name alternative tools, leaving some ambiguity for the agent.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds rich behavioral context: for companies, it pulls specific financials from SEC EDGAR/XBRL with off-calendar fiscal year handling; for drugs, it pulls FAERS, FDA approval, and trial counts. It also states results are sorted by primary metric and returns citation URIs.

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 longer but front-loaded with common query patterns. Every sentence adds value (examples, data sources, sorting behavior, citation URIs). Slight redundancy in explaining type, but overall efficient for the information density.

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

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

Given the tool's complexity (two entity types, different data sources, sorting, citations, and no output schema), the description covers all essential aspects: supported queries, data provenance, sorting, return format, and replacement for multiple lookups. Adequately complete for an agent to understand invocation and behavior.

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%, providing baseline for parameters. The description adds meaning beyond schema by explaining what each type returns (company financials vs drug data), specifying min/max items for values, and giving concrete examples (tickers, drug names). This adds value, but schema already covers the basics well.

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 side-by-side comparison of 2-5 companies or drugs, with explicit query examples like 'Compare X and Y' and 'rank these companies'. It distinguishes from siblings like entity_profile (single entity lookups) by emphasizing parallel comparison over sequential lookups.

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 'ALWAYS PREFER over sequential single-pack lookups when comparing entities', providing a clear when-to-use directive. It also gives examples of appropriate queries and explains the type parameter determines data sources (company vs drug), guiding correct invocation.

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

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

The description discloses behavioral traits beyond the annotations: it runs in parallel, returns a findings packet with verbatim evidence, confidence, source, fetched_at, and stable citations, and includes gaps[] for unanswered facets. It also warns that results may be empty for non-catalog topics. No contradictions with annotations (readOnlyHint: true, idempotentHint: true).

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 critical information (account requirement, alternatives). It is somewhat lengthy but each sentence provides necessary detail. Slight room for trimming, but overall effective.

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

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

Given the complexity of the tool, the lack of an output schema, and the annotations provided (readOnlyHint, openWorldHint, idempotentHint, destructiveHint false), the description fully explains the expected behavior and return format (findings packet with specific fields and gaps). It covers edge cases (empty gaps for uncatalogued topics) and prerequisites (account). It is contextually 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 good descriptions for both parameters. The tool description adds context that depth 'quick=3, standard=5, thorough=8' and that broad/multi-part questions are fine. It also adds the note that 'thorough' requires a paid plan, which is not in the schema. This adds meaningful value, warranting a 4.

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

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

The description clearly defines the tool as performing grounded multi-source research over Pipeworx's 1242 structured data sources, decomposing questions into facets and routing to 4,774 tools in parallel. It distinguishes from the sibling tool ask_pipeworx by specifying that deep_research is for broad/multi-part questions, while ask_pipeworx is for single lookups or breaking news.

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 deep_research (broad/multi-part questions over structured data) and when not to (single lookups: use ask_pipeworx; breaking/current news: prefer ask_pipeworx). It also notes account requirements and that depth 'thorough' needs a paid plan, and that the tool may return empty gaps for topics not in the structured catalog.

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 non-destructive behavior. The description adds crucial behavioral context: it returns 'top-N most relevant tools with names, descriptions, and full input schemas (with curated examples) — each result is ready to call directly, no second schema lookup needed.' This enriches the agent's understanding of the tool's output and efficiency. 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 concise (3 sentences) and front-loaded with the purpose. Every sentence adds value: purpose, usage context, and behavioral details about the return format. No redundant or filler content. Well-structured for quick parsing by an AI agent.

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 fully compensates by explaining the return format (names, descriptions, schemas with examples) and the fact that results are immediately callable. It also covers the single required parameter and its nature. The context signals (6 params, 100% coverage) are well-addressed. The description leaves no ambiguity about what the tool does and returns.

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 explains that the query accepts natural language and lists aliases, but this information is already present in the schema. It adds marginal value by providing usage examples ('e.g., "analyze housing market trends"'), but does not significantly extend parameter meaning beyond the schema. Score remains at baseline.

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

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

The description clearly states the tool's purpose: 'Find tools by describing the data or task.' It explicitly distinguishes itself from sibling tools by advising 'Call this FIRST when you have many tools available and want to see the option set.' The verb 'discover' and resource 'tools' are specific, and the listing of domain examples reinforces clarity.

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

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

The description provides explicit usage guidance: 'Use when you need to browse, search, look up, or discover what tools exist for...' and 'Call this FIRST...' It clearly tells the agent when to invoke this tool vs. other tools, and implies it's for exploration rather than direct answer retrieval. No alternative exclusions are needed given the clear positive directive.

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

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

Discloses the exact data sources (SEC EDGAR, XBRL, USPTO, news, GLEIF), the specific return fields (cik, recent_filings with URIs, fundamentals, patents with sunset note, news fallback, LEI), and the soft-failure behavior for patents. This adds significant 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 thorough but slightly verbose with multiple examples and details. However, every sentence adds value, and the front-loading with example queries is effective. Could be trimmed slightly without losing information.

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

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

Given the tool's complexity (multiple sources, no output schema), the description comprehensively covers what the tool returns, including edge cases like patent sunset and news fallback. It leaves no significant gaps for an agent to infer.

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 further meaning by specifying that ticker or zero-padded CIK is accepted, names are not, and that type is currently limited to 'company'. This provides practical usage details 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?

Starts with example queries that clearly illustrate what the tool does, then explicitly states 'full cross-source profile of a US public company in ONE parallel call'. This verb+scope definition distinguishes it from chaining single-source lookups.

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 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view'. Also warns that names are not supported and directs to use resolve_entity first, providing clear when-to-use and 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?

Description aligns with annotations (destructiveHint=true) and adds context about clearing sensitive data, but doesn't detail side effects like missing key behavior; idempotentHint covers that.

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 without waste, but 'by key' is slightly redundant given the schema; still concise and front-loaded.

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

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

For a simple one-parameter tool with no output schema and clear annotations, the description sufficiently covers purpose, usage, and parameter meaning.

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 minimal value beyond the schema's 'Memory key to delete'; baseline score applies.

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 action ('Delete a previously stored memory by key') and resource, and distinguishes from siblings remember and recall by focusing on deletion vs storage/retrieval.

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

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

Provides clear contexts for use (stale context, task done, clear sensitive data) and mentions pairing with siblings, but lacks explicit 'when not to use' or alternative 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 (readOnlyHint, idempotentHint, openWorldHint) indicate safety, and the description adds behavioral detail: it fetches an external page, extracts content, and outputs a markdown blob. No contradiction with annotations. It does not mention rate limits or auth, but given the annotations, the behavior is well-disclosed.

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

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

The description is two sentences plus a succinct 'Useful for' list. Every sentence is informative and front-loaded with key actions and results. No redundancy.

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

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

Given the tool has only two parameters and no output schema, the description explains the output format ('single text blob ready to drop at site-root/llms.txt'), return value, and use cases. Annotations cover safety. Complete for a simple tool.

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

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

Schema coverage is 100%, with both 'url' and 'max_links' described in the input schema. The description adds minimal extra beyond the schema, only implying the use of 'max_links' by mentioning 'key links'. Baseline 3 is appropriate.

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

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

The description clearly states the tool generates a production-ready llms.txt file for any URL, with specific actions: fetches page, extracts title/description/key links, and emits standard markdown format. It distinguishes from siblings by focusing on llms.txt generation, unlike 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 provides explicit use cases: getting a client's site indexed, drafting for own project, auditing competitor AI visibility. It does not explicitly state when not to use or alternatives, but the context is clear enough for an agent to decide.

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

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

Annotations already indicate readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the description adds only minor behavioral context (spot prices per troy ounce). 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 two sentences, no unnecessary words, and front-loaded with the core action.

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

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

With annotations covering safety and output schema present, the description is fairly complete. It could mention that the date must be in the past or provide more detail on return format, but overall sufficient.

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

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

Schema coverage is 100% with descriptions for all parameters. The description does not provide additional parameter-level information, but the schema is sufficient.

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

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

The description clearly states it retrieves metal prices for a specific historical date and returns spot prices per troy ounce. It distinguishes from the sibling 'get_latest' which presumably provides current prices.

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 mentions it is useful for tracking price changes or computing returns, which gives context but does not explicitly state when to prefer this over alternatives like 'get_latest' or when not to use it.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds that prices are per troy ounce and optional parameters, but does not disclose any additional behavioral traits beyond what annotations cover. Minimal added value.

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

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

The description is short, front-loaded with the main action, and contains no superfluous words. Every sentence earns its place.

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

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

The description covers the core purpose, units, and optional parameters. With annotations and output schema present, it does not need to explain return values. Slightly incomplete due to missing details like data freshness, but adequate for a simple read-only tool.

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

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

Schema coverage is 100%, so the description's mention of optional base currency and metal symbols mirrors the schema without adding new meaning. 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 tool retrieves the latest precious and base metal spot prices, specifying the resource (gold, silver, etc.) and scope. It is not a tautology and distinguishes itself from the sibling 'get_historical' which implies historical 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?

The description does not explicitly state when to use or when not to use this tool versus alternatives. It implies usage for latest spot prices, but lacks direct comparison or exclusions. The existence of sibling 'get_historical' is not leveraged for guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds value by detailing the return fields (id, type, params, etc.) and implying that active subscriptions are listed by default. 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 two sentences: first states the core function and return fields, second gives usage guidance. It is front-loaded, concise, and contains no unnecessary words.

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

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

Given no output schema, the description compensates by listing return fields. It covers the main purpose and parameter. However, it could briefly note that subscriptions are per-caller or mention pagination if applicable, but overall sufficient.

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

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

The schema covers 100% of the parameter (include_inactive) with a description. The tool description does not add any further meaning beyond the schema, so baseline score of 3 is appropriate.

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

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

The description clearly states it lists the caller's active subscriptions, specifying the returned fields (id, type, etc.). It distinguishes itself from sibling tools 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?

The description explicitly says to use this before adding more subscriptions or to find an id to cancel, providing clear context for when to invoke it. However, it does not mention when not to use it or alternative 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?

The description discloses behavioral traits like rate-limiting, free usage, no quota impact, and daily review. Annotations are neutral; description adds valuable context without contradiction.

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

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

The description is concise (5 sentences) but packs essential information: purpose, usage guidelines, behavioral notes. It is front-loaded with purpose, then usage, then constraints. 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 tool's simplicity and the presence of 35+ sibling tools (none for feedback), the description is fully complete. It covers all needed information for correct selection and invocation, including rate limits and content guidance.

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

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

The input schema already provides thorough descriptions for all 3 parameters (type, context, message). The tool description adds guidance on how to write the message (in terms of tools/packs) and what to avoid, enhancing usability 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 explicitly states the tool's purpose: to send feedback about bugs, features, data gaps, or praise. It defines each type clearly and distinguishes itself from sibling tools, none of which are for feedback.

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 when-to-use scenarios (bug, feature/data_gap, praise) and what not to do (don't paste user prompts). It also mentions rate limits (5 per identifier per day) and that the tool is free, offering clear usage context.

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

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

Annotations already mark the tool as read-only, idempotent, and non-destructive. The description adds valuable context: data source (CF analytics-engine), privacy (no PII), and caching behavior (5min-1h). No contradictions.

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

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

The description is concise and well-structured, using bullet points for use cases. Every sentence adds value without redundancy.

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

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

For a simple tool with one optional parameter and no output schema, the description thoroughly covers purpose, usage timing, data derivation, and caching. No additional information is necessary.

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 'window' parameter. The description adds semantic nuance: 'Shorter windows surface what's hot right now; longer windows show steady-state demand.'

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 function: returning top tools, top packs, and call volume over selectable windows. It lists three concrete use cases, differentiating it from sibling tools that focus on specific queries or historical 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?

The description provides explicit when-to-use scenarios (discovering hot data, confirming canonical tools, checking alignment). While it doesn't name alternative tools for different needs, the context is sufficient for an agent to decide appropriateness.

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 goes far beyond by detailing monotonicity violations, partition checks (sum of YES prices ≈1), semantic anchor with Jaccard similarity, partition filter for placeholder slugs, and fill_check against live CLOB depth. It warns that realizable_edge_pp ≤ 0 means the opportunity is not tradeable, which is crucial for correct agent behavior.

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

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

The description is well-structured with clear sections for each mode, semantic anchor, partition filter, and fill check. It is somewhat verbose but every sentence adds necessary detail. The purpose is front-loaded, and the response format is outlined. Minor redundancy could be trimmed, but overall it is effectively organized.

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

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

Despite having no output schema, the description comprehensively explains the response structure: 'opportunities[] (gap_pp, suggested_trade, reasoning, monotonicity violation context)', and in event mode 'partition_check{sum_yes_prices, gap_from_1, placeholders_filtered, suggested_trade}'. It also covers fill_check and custom sizing via polymarket_fill_risk. The tool's complexity is fully addressed, leaving no major 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 description coverage is 100%, so the schema already documents the parameters. The description adds significant context: for event mode, it 'walks child markets, checks date-axis/threshold-axis ordering AND computes the partition_check'; for topic mode, it 'searches related events across the platform, flattens markets, runs the comparator on the union'. It also provides example values (e.g., 'fed-decision-may-2026'). This enriches the schema's bare 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 defines the tool's purpose: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It distinguishes between three modes: no args (trending_scan), event (single event slug), and topic (cross-event scanning). This specificity contrasts with siblings like polymarket_edges and polymarket_fill_risk, making it easy to differentiate.

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: 'Call with NO args for a trending_scan', 'event (recommended for a specific market)', and 'topic (for cross-event scanning)'. It also explains when to use each mode (e.g., cross-event catches patterns single-event misses). However, it does not explicitly state when the tool should not be used, though the sibling list offers 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, destructiveHint. The description adds significant behavioral context: caching (1h at KV level), three response segments with detailed edge calculations (edge_pp_net, kelly_fraction), a 24h-move warning, and diagnostics showing why segments might be empty. 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?

At over 300 words, the description is dense but well-structured. It front-loads the core purpose, then systematically covers segments, knobs, fields, and diagnostics with clear numbering. While every sentence is valuable, it could be slightly more concise without losing information. Still, it earns its length given the tool's complexity.

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

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

Despite no output schema, the description fully explains the response structure (by_segment, diagnostics), all fields in each opportunity, caching, and limitations (fed unreliable without paid data). It provides enough detail for an agent to decide when to call and interpret results, compensating for the lack of a formal 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%, with all 9 parameters described. The description adds further nuance: 'min_kelly' explains it's half-Kelly and skips small opportunities, 'slippage_pp' explains Polymarket fees, 'min_partition_leg_kelly' explains its per-leg application distinct from min_kelly. This enhances understanding beyond the schema alone.

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

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

The description clearly states the tool scans top Polymarket markets and returns opportunities where Pipeworx data disagrees with market price. The verb 'scan' and resource 'top Polymarket markets' are specific. It distinguishes from siblings like 'polymarket_arbitrage' by positioning itself as a discovery tool for 'what should I bet on today' without paging hundreds of markets.

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 the tool is built for 'what should I bet on today' and that agents discover opportunities without paging hundreds of markets. It provides usage context for each model family and knobs like min_liquidity and max_spread_pp as tradeable-edge filters. The fed_note explains when the data is unreliable, 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?

The description adds significant behavioral context beyond the annotations: it explains data sources (daily snapshots), computation of trend and decay, snapshot gaps, and TTL. The annotations already indicate readOnlyHint, idempotentHint, and destructiveHint, and the description does not contradict them.

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 a clear opening, then details on arguments and response. It uses bold for key terms. While slightly long, it is not verbose and every sentence adds value.

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

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

Given the tool has 2 optional parameters, no output schema, and annotations are present, the description covers response fields (tracked, expired, snapshot_dates) and limitations (TTL, decay source). It is complete for an analytics tool.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining the 'days' parameter (lookback, default 14, max 30) and 'window' parameter (snapshot family, default '1wk'), along with response structure. This goes 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 that the tool provides 'edge persistence and decay telemetry' and answers specific questions about edge longevity. It uses a specific verb ('answers') and resource ('edge persistence'), and the detailed explanation distinguishes it from sibling tools like 'polymarket_edges'.

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

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

The description gives clear context for when to use the tool, such as understanding edge persistence and competition clocks. It also mentions limitations (60-day TTL, decay from daily closes). However, it does not explicitly state when not to use it or provide direct comparisons to 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, idempotentHint, and destructiveHint=false. The description adds extensive behavioral context: walks ladder, returns specific fields like slippage_pp, verdict, forced_directional_risk, and explains risks of partial fills. 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?

Description is relatively long but well-structured with clear headings (SINGLE-MARKET, BASKET) and a usage note. Each sentence adds value, though could be slightly more concise. Front-loaded with purpose and required parameters.

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 lists all return fields and their meanings (top_of_book, vwap_fill_price, etc.) and explains edge cases like thin_legs, forced_directional_risk. It also provides usage context and warnings, making it complete for a complex tool.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning beyond schema: explains size_usd interpretation in basket mode (settlement notional), default auto for side, and significance of parameters. Not all parameters have extra explanation (e.g., market and event are clear from schema), but 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?

Description starts with a clear, specific verb phrase: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It then distinguishes two modes (single-market and basket) with detailed behavior, making it perfectly distinct from siblings like polymarket_arbitrage or polymarket_edges.

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

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

Explicitly states when to use this tool: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains why (theoretical overround not capturable, partial fills cause unhedged positions), providing clear exclusionary guidance.

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

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

The description goes well beyond the annotations (readOnlyHint, idempotentHint) by detailing safety fields like compatibility_warning, temporal_alignment, and skip counters. It explains edge cases where the spread is not meaningful due to non-equivalent bet shapes or temporal misalignment, ensuring the agent understands the behavior's nuances.

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 information-dense and covers all critical aspects, but it is structured as a single long paragraph without clear separation of modes, safety fields, and response details. While front-loaded with the main purpose, the lack of structure (e.g., bullet points or sections) reduces readability and 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?

Despite no output schema, the description thoroughly explains the response structure (leg-by-leg prices, top_spreads_pp, safety fields) and covers all parameters and edge cases. Given the tool's complexity and the absence of an output schema, the description provides complete contextual information for correct usage.

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

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

The description adds substantial meaning beyond the schema: it explains the topic pre-mapped list (fed, btc, etc.), the override behavior for explicit tickers, and provides examples. With 100% schema coverage, the description compensates by giving usage context and allowed values, fully enriching the parameters.

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

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

The description clearly states the tool computes 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It explains the purpose with specific verb+resource and distinguishes two modes (topic shortcuts vs explicit tickers), setting it apart from sibling tools like polymarket_arbitrage which focus on single-venue opportunities.

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 each mode (topic shortcuts for common macro queries, explicit tickers for custom pairings) and warns that pre-mapped topics often return compatibility warnings rather than tradeable spreads. However, it does not explicitly compare against alternative tools or state when not to use it.

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

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

Annotations already indicate readOnlyHint=true, idempotentHint=true, destructiveHint=false. Description adds that it is scoped to identifier and pairs with remember/forget. Could mention what happens if key missing, but overall 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?

Two sentences, no wasted words. Action verb 'Retrieve' front-loaded. Efficient and clear.

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

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

For a simple key-value retrieval with one optional param and no output schema, the description fully covers behavior, scope, and pairing with sibling tools.

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

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

Schema coverage is 100% for the single optional parameter. Description clarifies that omitting key lists all keys, which is not explicit in schema description but present in examples. Adds value beyond schema.

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

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

The description clearly states it retrieves values saved via remember or lists all keys if omitted. It distinguishes from sibling tools remember and forget by specifying its read-only nature.

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

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

Explicitly says when to use (look up stored context) and provides alternatives (remember to save, forget to delete). Mentions scoping to identifier, giving clear context for usage.

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

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

Annotations declare readOnly, openWorld, idempotent, non-destructive. Description adds value by detailing returned fields, the effect of mark_read flag (flags events read, next call shows newer ones), and poll-friendliness. 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 main action, no fluff. Every sentence adds value, from what is returned to parameter hints to alternative access.

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 what is returned, filtering options, state management via mark_read, and usage scenarios (polls, scripts). No output schema, but description compensates by listing return fields. Could mention ordering or pagination, but not essential for a read-only list 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 descriptions cover 100% of parameters. Description adds examples (e.g., 'sec_8k' for type), clarifies default for mark_read (false), and explains the purpose of since parameter. Provides extra context 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 clearly states it pulls fired events from the subscription feed, returns most recent alerts with specific fields (source, citation_uri, raw payload). It distinguishes from siblings like get_historical or get_latest by specifying it's the persisted feed and mentions an alternative access URL for scripts, making purpose distinct.

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

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

Provides context: polling works fine, and the same feed is available via URL for scripts/dashboards. Implies when to use the tool vs direct access, but doesn't explicitly compare to sibling tools like list_subscriptions or get_latest.

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, destructiveHint=false, idempotentHint=true, openWorldHint=true, so the agent knows the tool is safe and read-only. The description adds behavioral details beyond annotations: it fans out to multiple sources (SEC, GDELT/GNews, USPTO), describes fallback logic, soft-fail for USPTO, and return structure (changes[] grouped by source, total_changes, citation URIs). No contradictions.

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

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

The description is a single dense paragraph with no wasted sentences. It front-loads examples for clarity, then covers sources, parameter formats, return structure, and alternative tool efficiently. Every sentence serves a purpose.

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

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

Despite having no output schema, the description fully explains the return shape (structured changes[] grouped by source, total_changes, URIs). It covers multi-source aggregation, fallback, soft-fail, time window formats, and the alternative tool. This is complete for a complex 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% (all 3 params have descriptions). The description adds extra meaning: for `type` it notes only 'company' is supported; for `since` it provides examples and suggests '30d' or '1m' for typical monitoring; for `value` it explains ticker or CIK format. This goes beyond the schema's basic descriptions.

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

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

The description clearly states the tool's purpose: a change feed for a company over a time window, with example queries like 'What's new with X' and 'latest on Y'. It also distinguishes from 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?

Explicit usage examples are provided, along with guidance on when not to use (e.g., 'Use entity_profile instead when you want the static profile...'). The description clarifies the `since` parameter format and mentions fallback behavior (GDELT→GNews), giving clear context for correct invocation.

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

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

Annotations already indicate it is not read-only, not destructive, and idempotent. The description adds context about session scoping ('scoped by your identifier'), persistence details ('authenticated users get persistent memory; anonymous sessions retain memory for 24 hours'), and key-value nature. No contradictions.

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

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

The description is concise yet comprehensive. It front-loads the purpose, then usage, then details about scope and pairing. Every sentence adds value without redundancy.

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

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

For a simple key-value storage tool without an output schema, the description provides complete information: what it does, when to use, behavioral traits, and links to sibling tools. No gaps remain.

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 clear descriptions for 'key' and 'value'. The description adds little beyond the schema; it mentions 'key-value pair scoped by your identifier' but doesn't provide additional semantic guidance.

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: 'Save data the agent will need to reuse later — across this conversation or across sessions.' It uses a specific verb ('save') and resource ('data'), and distinguishes from sibling tools 'recall' and 'forget' by mentioning them.

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 explains when to use: 'Use when you discover something worth carrying forward... so you don't have to look it up again.' Also provides guidance on pairing with 'recall' and 'forget' for retrieval and deletion.

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

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

Annotations already declare readOnly, openWorld, idempotent, non-destructive. Description adds internal cascading behavior (multiple internal lookups) and auto-disambiguation for company, 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?

Well-structured opening with query patterns, clear purpose, usage guidance, then details. Slightly verbose but every sentence adds value. 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?

Covers all necessary aspects: purpose, when to use, supported types with return values, internal behavior. No output schema but return values are described adequately. Complete for a lookup tool with good annotations.

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

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

Schema coverage is 100% with parameter descriptions. Description adds practical examples (ticker, CIK, name for company; brand/generic for drug) but does not introduce new semantics 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?

Description clearly states verb ('resolve') and resource ('name to identifier'), provides natural language examples, and explicitly says to use first when needing an ID. Distinguishes from sibling tools by positioning as the entry point for identifier lookup.

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 instruction to use first when name is present but ID is needed. Lists supported types and what each returns. Does not explicitly state when not to use or mention alternatives, but context is clear.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint. Description adds details: probes each entity with ai_visibility_check, ranks results, returns score/confidence/signal density. It also mentions _apiKey requirement for anthropic model. 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?

Description is three sentences, front-loaded with the core purpose. Every sentence earns its place: purpose, mechanism/use case, output. No redundancy or filler.

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

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

Given there is no output schema, the description explains the return format ('ranked list with score, confidence, signal density per entity'). It also clarifies the use case and comparison nature. The tool is simple enough that this level of detail suffices.

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

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

Schema coverage is 100% with descriptions for all 4 parameters. The tool description does not add new information beyond what the schema already provides (e.g., models list and _apiKey requirement are identical). Per rules, baseline is 3 when coverage is high and description adds no extra semantic value.

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

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

Description clearly states 'Compare AI visibility across multiple entities side-by-side', specifying the verb 'compare', resource 'AI visibility', and scope 'multiple entities'. It distinguishes from sibling tools like ai_visibility_check (single entity) and compare_entities (general comparison) by focusing on AI presence scores and rankings.

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

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

Description states it is 'useful for competitive AI-marketing audits' and gives example question, providing clear usage context. However, it does not explicitly mention when not to use it or direct users to alternative tools (e.g., ai_visibility_check for single-entity checks).

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

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

Annotations already declare readOnlyHint and idempotentHint; the description adds valuable behavioral context beyond that: partial failures degrade gracefully, bundlephobia's first measurement can take 5-30 seconds, and sources_failed is listed on timeout. This helps the agent handle delays and incomplete results.

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

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

The description is compact and well-structured: it starts with the core purpose, then lists data sources, provides usage guidance, notes limitations, and explains failure behavior. Every sentence adds value with no redundancy.

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

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

Given the tool's complexity (multi-source aggregation, no output schema), the description thoroughly covers return fields, edge cases (timeouts, partial failures), and ecosystem scope. It leaves no major gaps for an agent to navigate.

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

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

The input schema already provides full descriptions for both parameters (100% coverage). The tool description does not add new semantic detail about the parameters; it restates context already present. Baseline of 3 is appropriate.

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

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

The description clearly states it is a composite check for npm packages, aggregating data from deps.dev and bundlephobia. It distinguishes itself from sibling tools by specifying a unique function: evaluating safety, popularity, and size in one call.

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

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

Explicit use cases are given ('is X safe / popular / small', 'what does adding lodash cost me'). It also notes the NPM-only limitation and mentions fallback for other ecosystems. No direct comparison to sibling tools, but the guidance is clear and practical.

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

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

Adds significant detail beyond annotations: BGE-base-en embeddings, cosine similarity, 500-char windows, 200K char cap with truncation, and offset for verification. 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?

Three compact sentences: purpose, usage context, technical details. Every sentence earns its place, no fluff.

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

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

Covers key aspects: algorithm, truncation, offsets, pairing with another tool. Without output schema, still describes return format (passages with offsets and scores). Sufficient for a medium-complexity tool.

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

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

Schema coverage is 100%, but description adds examples for query, explains text as document body, and gives default/range for limit. Enhances understanding without being redundant.

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 performs semantic search inside a fetched record, with examples (SEC 10-K, article) and distinguishes from sibling ask_pipeworx_grounded by mentioning pairing.

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

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

Explicitly says use when the record is too big for the prompt, saves context, and returns only relevant passages. Pairs with ask_pipeworx_grounded, but doesn't list 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?

The description contradicts the annotations: annotations set idempotentHint=true, but the description implies each call creates a new subscription ID, meaning it is not idempotent. This inconsistency reduces transparency. Additionally, the description does comprehensively cover other behavioral aspects like delivery channels and caps.

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: the first sentence states the core purpose, followed by requirements, supported types, and delivery options. It is somewhat lengthy but every sentence adds value. Minor redundancy could be trimmed, but overall efficient.

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

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

Given the tool's complexity (3 parameters, nested objects, no output schema), the description is remarkably complete. It covers all necessary aspects: required authentication, type-specific filter formats, delivery options with constraints, and return value (subscription id). No major gaps are apparent.

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

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

The description adds significant meaning beyond the input schema. It provides detailed examples for each subscription type (e.g., items codes for sec_8k, topic for polymarket_edge) and explains delivery channel constraints (e.g., SMS verification, webhook signing). Schema coverage is 100%, but the description enriches the understanding of nested parameters.

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 creates a proactive monitoring subscription to a live-data event stream and returns the new subscription ID. It distinguishes itself from sibling tools like list_subscriptions, unsubscribe, and recent_alerts by specifying that it creates subscriptions for specific event types.

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 on when to use this tool (to set up alerts for specific event types) and includes prerequisites (Pipeworx OAuth account, phone verification for SMS). It lists supported types with examples but does not explicitly state when not to use it or give alternative tools for other use cases.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds behavioral context such as returning category-bucketed examples and that it draws from a live catalog. 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 slightly long but well-structured, front-loading the purpose and then providing detailed guidance. Every sentence adds useful information, but could be slightly more concise without losing meaning.

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

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

Given the simple tool (1 optional param, no output schema, rich annotations), the description covers all necessary context: what it does, how to use it, when to use it, and what it returns. It is complete for an onboarding tool.

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

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

Schema coverage is 100% with a single optional 'topic' parameter described. The description adds value by explaining the effect of omitting vs. providing a topic (full spread vs. focused), which goes beyond the schema's description of allowed values.

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 the onboarding entry point, returns category-bucketed example questions, and specifies exact tool+argument shapes. It distinguishes from sibling tools like ask_pipeworx and discover_tools by being the first tool to use when unfamiliar with Pipeworx.

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

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

Explicitly says use this tool FIRST when you don't know what Pipeworx can do, and describes when to call with no arguments versus with a topic. It also mentions learning how to call meta-tools, providing clear guidance on when to 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?

Adds significant behavioral details beyond annotations: ownership enforcement, deactivation (not deletion), and that historical events remain available via recent_alerts. 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?

Two sentences, no redundant words, front-loaded with action and key constraints.

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?

Complete for a simple 1-param tool with no output schema: purpose, side effects, ownership, and impact on related functionality are 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 covers the single parameter id with description. Baseline 3 is appropriate as description does not add extra semantics beyond schema.

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

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

Clearly states the action (cancel a subscription by id), the resource (subscription), and distinguishes 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?

Specifies when to use (to cancel a subscription), mentions ownership enforcement, and implies the id comes from subscribe. Could explicitly mention not to use for others' subscriptions, but context is clear.

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

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

Annotations already indicate readOnlyHint, idempotentHint, and destructiveHint=false. The description adds specifics: returns verdicts (confirmed, refuted, etc.), structured form, actual value with pipeworx:// citation, and percent delta. It also discloses data source (SEC EDGAR+XBRL) and the fact that it's a composite operation replacing multiple calls. 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 fairly long but well-structured: starts with examples, then use case, domain scope, output details, and comparative advantage. Every sentence adds value, though minor redundancy in examples could be trimmed.

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

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

Given no output schema, the description fully explains return values (verdict types, structured form, actual value, citation, delta). It covers purpose, usage, parameter, and behavioral aspects comprehensively for a single-parameter tool with high schema coverage.

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

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

Schema coverage is 100% with a clear description of the 'claim' parameter. The description provides additional context with multiple examples and explains that it accepts natural-language claims, adding value beyond the schema's definition.

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

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

The description clearly states the tool's purpose: verify natural-language claims against authoritative sources, specifically company-financial claims via SEC EDGAR+XBRL. It provides example queries like 'Is it true that...' and distinguishes itself from sibling tools by focusing on claim verification rather than general research or entity comparison.

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

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

The description explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct' and limits scope to company-financial claims. While it doesn't explicitly state when not to use, the domain restriction is clear. It also highlights that it replaces 4-6 sequential calls, providing efficiency guidance.

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