Soilgrids

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

The description reveals key behaviors: probing multiple models, scoring per model, default model (Workers AI), optional Anthropic with BYO key, return structure (score, confidence, signals, raw_response, combined view). Annotations already indicate readOnly, openWorld, idempotent; description adds cost and return details 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?

Three sentences front-loaded with purpose, then default model and API key, then returns and use cases. No fluff; each sentence earns its place.

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

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

Despite no output schema, the description details the return format. Given 100% schema coverage, good annotations, and clear sibling differentiation, it is complete. No gaps remain for an agent to use this tool correctly.

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

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

Schema covers all 4 parameters, but description adds meaning: explains default model for 'models', how _apiKey works (BYO key), and context disambiguation. Baseline 3; description provides extra value.

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

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

The description clearly states the tool probes LLMs and scores visibility (0-100). It specifies the verb 'probe', resource 'LLMs', and outcome 'score visibility'. It distinguishes from siblings like scan_competitor_ai_presence by focusing on general brand/product topic visibility.

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

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

The description lists use cases: AI-marketing audits, pre-launch brand checks, competitive monitoring. While it does not explicitly say when not to use it or name alternative tools, it provides clear context for when the tool is applicable.

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

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

Beyond annotations (readOnlyHint, openWorldHint, etc.), the description adds critical behavioral context: routes to 4,552 tools across 1,160 sources, fills arguments, returns structured answer with stable pipeworx:// citation URIs, and that it's one fast call on every tier. 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 lengthy but front-loaded with the most important advice (prefer over web search), structured with examples and clear differentiation. A bit verbose but well-organized, earning a 4.

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 a general-purpose query tool, the description is exceptionally complete: covers purpose, usage, alternatives, examples, return format (structured with citations), and behavioral details. No output schema exists, but description adequately describes what to expect.

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

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

Schema coverage is 100% with clear parameter descriptions and aliases. The description adds examples but does not provide additional semantic detail beyond what the schema already covers. 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's purpose: answering factual questions about current/historical data from authoritative sources. It explicitly says 'PREFER OVER WEB SEARCH' and lists many data types (SEC filings, FDA, etc.), distinguishing it from siblings like ask_pipeworx_grounded and deep_research.

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

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

Provides explicit when-to-use guidance: 'START HERE for most questions' and 'Use whenever the user asks...'. Also specifies when to step up to alternatives ('if need hallucination-resistant single answer use ask_pipeworx_grounded; for broad/multi-part use deep_research'), with examples.

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, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds valuable context: the refusal mechanism (with specific refusal reasons), the extraction process (using only tool result data), and the extra LLM call cost. 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 fairly long but efficiently packed with critical details (purpose, use cases, trade-off, return format). It is front-loaded with the core concept. Minor verbosity in listing aliases but overall well-structured.

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

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

Given the complexity of a two-tier decision process (routing vs extraction), the description fully covers behavior: what it does, when to use, what returns on success/failure, and the cost trade-off. No output schema exists, but return structure is explicitly described.

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

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

Schema description coverage is 100%, so the schema documents all parameters. The description just restates that it accepts a natural language question and lists the same aliases as the schema. It adds no new semantic meaning beyond what the schema provides.

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

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

The description defines a specific verb-resource pair: 'hallucination-resistant answer mode' using Pipeworx tool routing. It distinguishes itself from sibling 'ask_pipeworx' by describing the grounded extraction process and explicit refusal reasons. The purpose is clear 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: 'Use whenever an answer will be quoted, cited, or acted on...' and when to prefer the alternative: 'prefer ask_pipeworx for casual lookups.' Also notes the extra LLM call cost as a trade-off.

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, establishing a safe, read-only profile. The description goes far beyond annotations, detailing fan-out examples for 13+ market categories, response shapes (market, analysis, evidence), resolver confidence levels, parent event extraction, news fallback fields, safety short-circuits, and cancellation rule parsing. No contradictions with annotations.

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

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

The description is very long and dense, containing many examples and edge cases. While each sentence provides value, the length exceeds what is necessary for a typical tool. It would benefit from clearer section breaks (e.g., 'Usage', 'Parameters', 'Safety'). The core purpose is front-loaded, but the detail makes it less concise.

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

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

Given the tool's high complexity (multiple fan-out patterns, resolver contract, parent events, news fallbacks, resolution-rule risk) and the absence of an output schema, the description covers virtually every behavioral aspect. It addresses common pitfalls (low-confidence matches, closed markets, wide spreads) and provides complete guidance for the agent to invoke the tool correctly.

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

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

Schema coverage is 100% (all 3 parameters have descriptions). The description adds substantial value beyond the schema: it explains how market_input examples work (slug, URL, question text), that depth defaults to thorough and controls evidence count, and that include_raw true returns full upstream payloads (50KB-500KB) versus summaries (~20KB). This semantic depth aids correct parameter selection.

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 opens with a clear verb and resource: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies the scope (one call, one bet) and distinguishes itself from sibling tools like polymarket_edges and polymarket_arbitrage by focusing on comprehensive data gathering for a single market.

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

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

The description explicitly states use cases: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It also covers blocking scenarios (low-confidence matches, closed markets) that guide when not to proceed. However, it does not explicitly contrast with siblings like ask_pipeworx or polymarket_edges, leaving some ambiguity.

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

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

Beyond annotations (readOnlyHint, idempotentHint), the description discloses data sources (SEC EDGAR/XBRL for companies, FAERS/FDA/trials for drugs), handling of off-calendar fiscal years, sorting by primary metric, and return format with citation URIs. No contradiction with annotations.

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

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

The description is well-structured and front-loaded with examples, but slightly verbose. Each section adds value, so it earns its length, but could be trimmed slightly without loss of clarity.

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

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

Given the tool's complexity (two entity types, multiple data sources, sorting, citations) and the absence of an output schema, the description is remarkably complete. It covers usage context, data behavior, parameter details, and output format, enabling correct agent invocation.

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

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

The description adds significant meaning beyond the schema: for 'type' it explains the difference in pulled data (financials vs. regulatory/safety), and for 'values' it provides format guidance (tickers/CIKs vs. drug names). This enriches the schema descriptions which were already present.

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 comparisons of 2–5 companies or drugs in one call, with specific example queries. It distinguishes itself from sibling tools by explicitly preferring over sequential single-entity lookups, and mentions it replaces 8–15 sequential calls.

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

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

It gives strong guidance to prefer this tool over sequential lookups for comparisons, with example phrases. However, it does not explicitly state when NOT to use it (e.g., for single entities), though this is implied by the '2–5' constraint.

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 context beyond the annotations: it explains the parallel decomposition into facets, the expected time (15-60s), the return packet structure (verbatim evidence, confidence, source, fetched_at, pipeworx:// citation, gaps[]), and that it never invents. This complements the readOnlyHint and idempotentHint annotations.

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

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

The description is relatively long but highly efficient and well-structured. Every sentence adds value, covering purpose, usage, behavior, parameters, and limitations. It is front-loaded with key information (account requirement and alternatives) and uses clear separations.

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 (parallel research across many sources, 1160 data sources, 4,552 tools), the description is remarkably complete. It explains what the tool does, when to use it, what it returns, what it cannot do, and even provides an expectation for response time. No output schema exists, but the return packet is described adequately.

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

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

Schema coverage is 100%, but the description adds critical meaning: it explains the 'depth' enum values (quick=3, standard=5, thorough=8) and notes that 'thorough' requires a paid plan. It also clarifies that the 'question' parameter accepts natural language and multi-part queries.

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: 'Grounded multi-source research across Pipeworx's 1160 STRUCTURED data sources... in ONE call'. It uses a specific verb ('research') and resource ('structured data sources'), and distinguishes itself from siblings like ask_pipeworx and bet_research.

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 and when-not-to-use guidance. It recommends using this tool for broad/multi-part questions over structured data, and advises using ask_pipeworx for single lookups or breaking news. It also warns that topics not in the structured catalog will return empty gaps, and mentions account requirements.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the tool is safe and idempotent. The description adds behavioral details: 'Returns the 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 goes beyond annotations, but does not disclose all edge cases (e.g., behavior when no 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?

Description is tightly written in about 5 sentences, front-loaded with purpose, then examples, then return value, then usage advice. 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?

Despite no output schema, the description fully explains the return format (names, descriptions, schemas, examples, ready-to-call). It addresses the parameter count and aliases. Given the tool's role as a discovery meta-tool with clear annotations, this is complete.

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

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

Schema coverage is 100% with descriptions for all 6 parameters. The main description reiterates that 'Accepts task, q, description, search as aliases,' which duplicates schema info. It does not add meaningful new semantics beyond what the schema provides. Baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose: 'Find tools by describing the data or task.' It provides extensive domain examples and distinguishes itself from sibling tools by advising to 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).'

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

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

Explicit usage guidance is given: 'Use when you need to browse, search, look up, or discover what tools exist for: ...' and 'Call this FIRST when you have many tools available...' This clearly tells the agent when to invoke the tool versus alternatives.

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

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

Annotations already indicate read-only, open-world, idempotent, non-destructive behavior. The description adds critical behavioral details: fans out across multiple sources, patents may soft-fail after May 2025 (USPTO API sunset), and it requires ticker or CIK input. No contradictions.

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

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

The description is well-structured with front-loaded example queries and a bullet-like list of returns. While comprehensive, it is slightly verbose but each sentence adds value.

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

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

Given the tool's complexity and lack of output schema, the description thoroughly explains all outputs (filings, fundamentals, patents, news, LEI) and limitations (patents soft-fail). It covers prerequisites and fallback behavior, making it 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 has 100% coverage with descriptions for both parameters. The description adds examples (e.g., 'AAPL', '0000320193') and reiterates that names are not supported, enhancing understanding beyond the schema.

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

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

The description clearly states the tool provides a 'full cross-source profile of a US public company in ONE parallel call' with example queries like 'Tell me about X'. It distinguishes from siblings such as resolve_entity by specifying it takes ticker or CIK, not names.

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' for holistic views. Also advises using resolve_entity if only a name is available, providing clear when-to-use and alternatives.

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

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

Annotations already set destructiveHint=true and idempotentHint=true. Description confirms deletion but adds no new behavioral details beyond annotations. No contradiction.

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

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

Two sentences covering purpose, usage, and related tools. No superfluous information. Front-loaded with the primary 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?

Given the tool's simplicity (one required parameter, no output schema), the description is complete. It explains what it does, when to use it, and how it relates to 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 describes 'key' as 'Memory key to delete'. Description adds context by saying 'by key' and implying it references a previously stored memory, adding 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?

Explicitly states 'Delete a previously stored memory by key'. Verb 'delete' and resource 'memory' are clear. Distinguishes from sibling tools 'remember' and 'recall'.

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

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

Provides three specific usage scenarios: stale context, task done, clearing sensitive data. Also advises to pair with 'remember' and 'recall', offering clear guidance on when 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?

Description explains internal behavior (fetch, extract, emit) and output format, adding value beyond annotations which only declare readOnly, openWorld, idempotent, and non-destructive.

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

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

Five sentences with front-loaded purpose, concise details, and use cases; 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?

For a simple tool with 2 params and no output schema, description covers purpose, behavior, and usage contexts adequately.

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

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

Schema coverage is 100%, so baseline is 3. Description adds default and max values for max_links and context for URL, but not substantial beyond schema.

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

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

Description clearly states the verb 'generate' and resource 'llms.txt file', specifies purpose for AI crawlers, and distinguishes from sibling 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?

Lists three explicit use cases (client site, own project, auditing competitor), but does not provide 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 already indicate readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds the valuable information that the tool may take several seconds to respond, which is behavioral context beyond the annotations. No contradictions.

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

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

The description is extremely concise with two sentences that front-load the purpose and add a usage hint and performance note. Every word earns its place, with no redundancy or 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?

Given no parameters and no output schema, the description covers the tool's purpose, use case, and a behavioral trait (slowness). It provides enough context for an agent to decide when to use it. Minor omission might be the exact output format, but it's acceptable for a simple 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?

The tool has no parameters, and the schema coverage is 100%. The description does not need to add parameter-level detail. Per calibration, a score of 4 is appropriate when no parameters are present and the description is clear.

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

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

The description specifies a clear action ('List'), a distinct resource ('soil properties from ISRIC SoilGrids'), and what it returns ('names and available depth intervals'). It differentiates from sibling tool 'soil_properties' which likely uses property codes, making the purpose unambiguous.

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

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

The description explicitly states to use this tool 'to discover valid property codes for soil_properties', providing a clear use case. It also notes 'Keyless; may take several seconds to respond', which sets expectations. However, it does not list specific alternatives or when not to use it, but the guidance is sufficient for a parameterless tool.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds that the tool returns specific fields but does not disclose additional behavioral traits beyond what is already clear from 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 with no fluff. The first sentence states purpose and return fields, the second provides usage context. 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?

Given 100% schema coverage, annotations, and a single optional parameter, the description sufficiently covers what the tool does, what it returns, and when to use it. No output schema exists, but return fields are listed.

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

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

The input schema has 100% coverage on parameters with a description for include_inactive. The description does not add new meaning to the parameter beyond the schema, so 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 'List the caller's active subscriptions', specifying the verb (List) and resource (subscriptions) with scope. It also lists return fields, distinguishing it from sibling tools like subscribe and unsubscribe.

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 this to review what you're monitoring before adding more or to find an id to cancel.' It does not explicitly mention alternatives but gives clear context for when 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?

Discloses rate limiting ('5 per identifier per day'), free usage, and team reading frequency. Annotations are minimal, so description carries burden well. 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 well-structured with clear front-loading of purpose, then usage, then behavioral details. Slightly verbose but every sentence adds value.

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

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

For a feedback tool with 3 params and no output schema, the description covers purpose, usage, behavioral traits, and parameter meaning fully. No gaps.

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

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

Schema coverage is 100%, baseline 3. Description adds meaning by explaining enum values (type) and giving content guidance for message and context fields, going beyond schema.

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

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

Description clearly states the tool's purpose: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' Specifies use cases (bug, feature, data_gap, praise) and differentiates from sibling tools by being unique 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?

Explicitly states when to use: 'Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' Provides guidance on what to include and not include.

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 adds value beyond annotations: explains data source (CF analytics-engine), no PII, caching behavior (5min-1h). No contradiction with readOnly, openWorld, idempotent hints.

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

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

Two sentences plus a list, front-loaded with main purpose, no redundant information. 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 simple tool (1 optional param, no output schema), description covers purpose, use cases, data source, caching, and parameter behavior fully.

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

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

Schema already covers parameter (window) with enum and description. Description adds contextual guidance on shorter vs longer windows, enhancing understanding.

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

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

Description clearly states verb ('returns'), resource ('top tools, top packs, and total call volume'), and scope ('recent window'). Distinguishes from siblings like 'discover_tools' and 'ask_pipeworx'.

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

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

Explicitly lists three use cases, providing context for when to use. Does not explicitly state alternatives or when not to use, but implied by use case descriptions.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds extensive behavioral details beyond annotations: internal logic (monotonicity, partition-sum, Jaccard similarity, placeholder filtering, fill check against live CLOB depth), all consistent with annotations. No contradictions.

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

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

The description is long but well-structured: first sentence summarizes purpose, then details each mode and technical checks (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK). Every sentence adds value given the tool's complexity. Slightly verbose but appropriate.

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

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

No output schema, so description fully explains response structure: opportunities array with fields, partition_check object in event mode, fill_check explanation. Covers edge cases like skipped_low_similarity, placeholders, and fill check conditions. Mentions alternative tool. Complete for the tool's complexity.

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

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

Schema covers both parameters with 100% coverage, but description adds significant meaning: explains event slug/URL format, what event mode does (walks child markets, checks ordering, partition_check), and what topic does (searches related events, runs comparator). Provides examples and clarifies semantic anchor and partition filter.

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

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

The description clearly states the tool finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks, with specific verb and resource. It distinguishes between two modes (event and topic) and indirectly differentiates from sibling tools like polymarket_edges by focusing on arbitrage detection with specific methodologies.

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

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

Explicit guidance on when to call with no arguments for trending_scan, when to use event vs topic parameters, and when not to trade based on fill check results. Also recommends alternative tool polymarket_fill_risk for custom sizing, providing clear context and exclusions.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds extensive behavioral context beyond annotations: caching behavior (1h at KV level keyed on all knobs), detailed model families, diagnostics for debugging empty results, and the interplay of parameters like min_kelly vs min_partition_leg_kelly. No contradictions.

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

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

The description is quite long but well-structured with labeled sections (model families, knobs, response top-level). It front-loads purpose and segments. However, it could be more concise by trimming redundant explanatory details, especially given the wealth of information in the response structure description.

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 comprehensively explains the response structure (by_segment, fed_candidates, _diagnostics) and what each opportunity carries (edge_pp_net, kelly_fraction, etc.). It also covers caching, diagnostics for empty segments, and tradeable-edge filters, leaving no ambiguities for agent invocation.

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

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

Schema coverage is 100% with parameter descriptions. The description adds meaning beyond schema by explaining parameter interactions (e.g., how min_kelly and min_partition_leg_kelly apply to different segments, slippage_pp default reasoning) and placing parameters in the context of the overall algorithm.

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

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

The description clearly states the tool scans Polymarket markets for edge opportunities where Pipeworx data disagrees with market price, positioning it for 'what should I bet on today'. It distinguishes itself from siblings like polymarket_arbitrage and polymarket_edge_tracker by detailing its unique multi-model approach (three segments) and knobs, making it the comprehensive edge discovery tool.

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

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

The description gives explicit context for daily edge discovery, explains the three segments, and details tradeable-edge knobs for filtering. However, it does not explicitly state when not to use this tool versus alternatives like polymarket_arbitrage, or conditions where a simpler tool suffices.

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

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

Annotations declare readOnlyHint, idempotentHint, and non-destructive. The description elaborates on reading snapshots, returning time-series, trend, decay, and interpretation of negative edges. No contradictions found.

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

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

The description is front-loaded with purpose and efficiently details response structure. While slightly verbose, each sentence adds value and no redundancy. Could be tightened slightly but well-structured.

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

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

Given complexity (time-series telemetry, multiple output fields) and lack of output schema, the description thoroughly explains returned objects, fields, and limitations. It fully compensates for missing output schema.

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

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

Schema covers both parameters with descriptions. The description adds defaults, clamping range, and explicit window families, exceeding schema info. With 100% schema coverage, the baseline is 3, but enrichment earns a 4.

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

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

The description clearly states the tool provides edge persistence and decay telemetry from daily snapshots, with explicit contrast between fresh and old edges. It distinguishes from sibling polymarket_edges by focusing on temporal analysis rather than raw edge 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 implies usage context (when you need to know edge longevity and decay) and provides limits (60-day TTL, not intraday). However, it does not explicitly exclude alternatives or compare to siblings like polymarket_edges, which could lead to confusion.

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 accurately reflects the annotations (readOnlyHint, idempotentHint, destructiveHint) by describing a read-only check with no destructive side effects. It adds behavioral context beyond annotations, such as the requirement for either 'market' or 'event' parameter, the walking of the order-book ladder, and the return of a verdict. This is sufficient given the annotations already convey safety and idempotency.

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

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

The description is well-structured with clear sections (REQUIRES, SINGLE-MARKET, BASKET) and uses capitalization for emphasis. While it is lengthy, every sentence adds necessary detail for the tool's complexity. A slight reduction could improve conciseness, but the current structure is highly informative and aids in quick parsing.

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?

Without an output schema, the description fully enumerates all return fields for both modes (e.g., top_of_book, vwap_fill_price, slipage_pp for single-market; theoretical_sum, capture_ratio, thin_legs, forced_directional_risk for basket). It also covers important edge cases like thin books and partial fills, and explains the risk of directional exposure. This makes the tool's behavior completely understandable without additional documentation.

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

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

Schema coverage is 100%, but the description greatly enriches each parameter's meaning. For example, it explains that 'size_usd' in single-market mode means 'max spend on buys, target proceeds on sells', and in basket mode it is 'settlement notional'. It clarifies the 'side' default logic for basket mode ('auto — sell if partition sum > 1, buy if < 1'). These details go well beyond the minimal schema descriptions.

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

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

The description clearly states it performs a 'realizable-vs-theoretical edge check' against live order-book depth. It distinguishes two modes (single-market and basket) and specifies the outputs for each. It also references sibling tools (polymarket_arbitrage, polymarket_edges) to clarify its role, ensuring no confusion with related functionality.

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

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

The description explicitly instructs 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It explains why: theoretical overround on thin books is not capturable, and partial basket fills convert an arb into an unhedged directional position, which is the dominant loss mode. This provides 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?

Beyond annotations (readOnlyHint, idempotentHint), the description explains the spread calculation formula, the meaning of safety fields like compatibility_warning, temporal_alignment, and the skipped counters. It discloses that real spreads are rare, which is crucial for correct agent interpretation.

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

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

The description is detailed but well-structured: purpose first, then modes, response format, safety fields. Every sentence adds value, though it could be slightly more compact. No unnecessary repetition.

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

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

Given the tool's complexity (cross-venue comparison, multiple safety checks, no output schema), the description is exceptionally thorough. It covers return values (leg-by-leg prices, top spreads, compatibility warning, temporal alignment) and common pitfalls, making it fully self-contained.

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

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

Schema coverage is 100% with descriptions for all three parameters. The description adds meaningful context by explaining how the two modes work and how parameters override each other. While schema already covers basics, the description enriches understanding of parameter interactions.

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 calculates cross-venue spread between Kalshi and Polymarket for the same resolving question. It distinguishes two modes (topic shortcuts and explicit tickers). Compared to siblings like 'polymarket_arbitrage', this is a distinct multi-venue tool.

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

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

The description provides explicit guidance on when to use each mode ('topic' vs explicit tickers), details the safety fields that indicate when spreads are meaningful, and honestly states that most pre-mapped topics return warnings, managing expectations effectively.

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

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

Annotations already provide readOnlyHint, idempotentHint, and destructiveHint. The description adds value by explaining scoping to identifier and the dual behavior (retrieve one key vs list all), which goes beyond annotations.

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

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

Three sentences, front-loaded with the core action, then usage context, then scope. No wasted words; highly efficient.

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

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

Given the tool's simplicity, annotations cover safety, and the description explains return behavior (value vs list). No output schema needed. Completes the picture for an agent.

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

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

Input schema has 100% coverage with one parameter ('key') described. The description adds meaning by explaining that omitting the argument lists all keys, which is not fully captured by the schema description 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 retrieves a previously saved value via 'remember' or lists all keys when the key argument is omitted. It uses specific verbs and resources, distinguishing it from sibling tools like 'remember' and 'forget'.

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

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

The description explains when to use the tool (to look up context stored earlier) and mentions the scope (scoped to identifier). It pairs with 'remember' and 'forget', providing clear context, though it does not explicitly state when not to use 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 read-only, idempotent, non-destructive. Description adds behavior details: mark_read flag effect, return fields, polling suitability, and alternative endpoint. 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?

Concise paragraph of 5 sentences. Front-loaded with main purpose, then details. No redundant or extraneous 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 return format (source, citation_uri, payload), filtering, mark_read behavior, polling, and alternative access. No output schema so description adequately 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%, so baseline is 3. Description adds extra context: explains mark_read in more depth, gives example type 'sec_8k', clarifies 'since' parameter as ISO timestamp.

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 it pulls fired events from subscription feed, with specific fields and filtering options. Distinguishes from siblings like list_subscriptions by focusing on alerts themselves.

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

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

Mentions polling works and an alternative endpoint, but does not explicitly contrast with sibling tools or provide when-not-to-use guidance. Implied usage for programmatic polling.

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, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds valuable behavioral context: fans out to SEC EDGAR, GDELT→GNews fallback, USPTO soft-fails, date format examples, and returns structured changes with citation URIs. No contradictions.

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

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

The description is a single, well-structured paragraph. It front-loads example queries, then concisely explains the tool's behavior, sources, date handling, fallback, and return structure. Every sentence is informative without redundancy.

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

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

Given 3 parameters, 100% schema coverage, and no output schema, the description is remarkably complete. It covers all essential aspects: what sources are queried, how dates work, fallback logic, return format, and a clear pointer to an alternative tool. No gaps identified.

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

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

All three parameters have descriptions in the schema (100% coverage). The description adds value by specifying input formats (ISO date, relative shorthand like '7d', '30d'), recommending '30d' or '1m' for monitoring, and explaining that value can be ticker or CIK. This enriches understanding beyond the schema.

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

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

The description starts with clear example queries ('What's new with X', 'latest on Y') and explicitly states the tool provides a change feed for a company over a time window. It distinguishes from the sibling tool entity_profile, making the purpose unmistakable.

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 concrete guidance on when to use this tool (e.g., 'What's new with X') and when to use the alternative entity_profile ('Use entity_profile instead when you want the static profile...'). It also details the fallback behavior from GDELT to GNews, setting clear expectations.

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 discloses behavioral traits beyond annotations: persistence differences for authenticated vs anonymous users (24 hours), scoping by identifier. Annotations already indicate idempotent and non-destructive, which description complements.

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

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

Four sentences, front-loaded with core purpose. Every sentence adds value: purpose, when to use, persistence details, and pairing with siblings. No fluff.

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

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

For a 2-param tool with no output schema, the description covers key aspects: use case, scoping, persistence, and lifecycle. Complete and actionable.

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

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

Schema coverage is 100% with descriptions for key and value. The description adds examples and naming conventions (e.g., 'subject_property'), enriching the schema without redundancy.

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

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

The description clearly states the tool's purpose: 'Save data the agent will need to reuse later' with specific examples like 'a resolved ticker, a target address, a user preference'. It distinguishes from sibling tools by mentioning 'recall' and 'forget'.

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

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

Explicitly tells when to use: 'when you discover something worth carrying forward' and pairs with 'recall' and 'forget' for alternatives. Provides context on scoping and persistence.

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, and non-destructive hints. The description adds behavioral context beyond annotations: internal cascading through multiple lookup endpoints and replacement of manual lookups. This enriches the agent's understanding 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 but comprehensive, front-loaded with user-friendly examples and a clear directive. Every sentence serves a purpose: examples, usage guidance, type details, and output explanation. 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 moderate complexity (2 parameters, 2 types, no output schema), the description is fully complete. It covers input meaning, expected output, internal behavior, and even notes the tool replaces multiple manual steps. 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%, but the description significantly adds value by providing concrete examples for the 'value' parameter (ticker, CIK, name for company; brand or generic for drug) and explaining what each type returns (e.g., ticker + CIK + URI for company; RxCUI + ingredient + URI for drug). This goes well beyond the schema.

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

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

The description clearly defines the tool's purpose: resolving a user-spoken name to a canonical identifier. It provides specific examples (ticker, CIK, RxCUI) and distinguishes from siblings by stating it replaces 2-3 manual lookups. The verb 'resolve' and resource 'entity' are clear.

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

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

The description explicitly advises 'Use FIRST whenever you have a name but need an ID,' providing clear when-to-use guidance. It details supported types and inputs. However, it does not mention when not to use it or name alternative tools, leaving a small gap.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false, establishing safety. The description adds context: it probes each entity, ranks them, and requires an API key for certain models. This goes beyond annotations, though it does not detail error handling or rate limits.

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 main purpose, and each sentence adds value. It efficiently covers usage, process, and output without redundancy.

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

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

Given the tool's complexity (multi-entity, optional API key, context), the description explains the output structure (ranked list with score, confidence, signal density) and the probe process. It lacks an explicit example or format details, but is sufficient for basic understanding without an 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?

All parameters have schema descriptions (100% coverage), so baseline is 3. The description adds meaning by noting that the first entity is treated as the 'subject' for narrative and that the tool probes each entity with ai_visibility_check. This enriches understanding beyond the schema.

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

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

The description clearly states the tool's purpose: 'Compare AI visibility across multiple entities side-by-side.' It specifies the verb (compare), resource (AI visibility), and outcome (ranked list with scores). It distinguishes itself from sibling tools like ai_visibility_check (single entity) and compare_entities (general comparison) by focusing on competitive AI-marketing audits.

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

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

The description provides a clear use case: 'Useful for competitive AI-marketing audits: does Claude know about us as well as our competitors?' It implies the tool wraps ai_visibility_check, but does not explicitly state when to avoid using it or mention alternative sibling tools. The context is sufficient for optimal use.

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

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

Annotations already indicate readonly, open world, idempotent, non-destructive. The description adds valuable behavioral context: partial failures degrade gracefully, bundlephobia timeouts (5-30s), sources_failed field returned, and returns specific summary fields. 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?

Description is long but front-loaded with the core purpose. It is well-structured with clear sections (what it does, when to use, return values, limitations). Could trim some redundant phrases, but overall efficient for the 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?

Given no output schema, the description thoroughly explains return content (summary block, per-advisory detail, links, alternative versions). Covers edge cases (scoped packages, partial failures, version default, ecosystem limits). Fully informs invocation.

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

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

Input schema has 100% description coverage for both parameters (package, version). The description adds minor value: confirming scoped packages are accepted and version defaults to latest. Baseline 3 is appropriate as schema already handles parameter meaning 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 composite functionality across deps.dev and bundlephobia for npm packages, using specific verbs like 'scan' and 'check'. It distinguishes from sibling tools like 'validate_claim' or 'bet_research' by focusing on dependency 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?

Explicitly states when to use: when an agent asks about safety, popularity, size, or cost of adding an npm package. Also specifies ecosystem (NPM only) and mentions fallback for other ecosystems via deps.dev, providing clear boundaries.

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

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

Adds technical details beyond annotations: BGE-base-en embeddings, cosine similarity, 500-char windows, 200K char cap with truncation flag. 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 well-structured sentences, front-loaded with purpose, followed by usage and technical details. No redundant text.

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

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

Describes return format (top-N passages with offsets and scores), algorithm details, and pairing with sibling tool. No output schema, so description compensates fully.

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 and clarifies max char limit for text, adding 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?

Description clearly states 'Semantic search INSIDE a fetched record' with a specific verb and resource. It distinguishes from sibling tools that fetch or ground over entire documents.

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 to cram into the prompt' and mentions alternative 'Pairs with ask_pipeworx_grounded' for grounding over passages.

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. Description adds value by noting the tool is keyless and may be slow, which are important behavioral traits not covered by 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 that efficiently convey purpose, source, output details, keyless access, and latency. No unnecessary information.

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

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

With no output schema, description adequately explains the return value (most probable class plus top 5 with probabilities). All necessary context for a simple 2-parameter tool is provided.

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 parameters are well-documented. Description does not add any additional meaning or context about latitude/longitude 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?

Description clearly states the verb 'Get' and the resource 'World Reference Base (WRB) soil classification at a coordinate', with examples of soil classes. It distinguishes from sibling tools like list_soil_properties which likely deal with different 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?

Description mentions it is 'keyless' and 'may take several seconds', giving usage context. However, it does not explicitly state when to use this tool versus alternatives like list_soil_properties or soil_properties, nor 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 confirm idempotent, read-only, non-destructive behavior. The description adds valuable context about latency ('may take several seconds') and unit scaling ('real units'), enhancing transparency beyond annotations.

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

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

The description is three sentences with no redundancy. It front-loads the core action and list of properties, then adds key operational notes. Every sentence serves a purpose, making it efficient and easy to scan.

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

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

The tool lacks an output schema, yet the description only vaguely mentions 'real units'. It does not specify the response format or how properties are returned (e.g., keys, units for each). Given the complexity (4 parameters, many codes), more detail on output would improve completeness.

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

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

Schema coverage is 100% with descriptions for all 4 parameters. The description adds minimal extra information, restating defaults for depth and properties. It does not provide new details beyond what the schema already conveys, so 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 retrieves soil property values at any coordinate from ISRIC SoilGrids, listing specific properties. It distinguishes itself from siblings like 'list_soil_properties' (which lists available properties) and 'soil_classification' by explicitly focusing on fetching values for a given point.

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 'Keyless' and a latency warning, but lacks explicit guidance on when to use this tool versus alternatives like 'soil_classification'. It does not state prerequisites or common use cases, leaving the agent to infer appropriateness from the purpose alone.

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 details beyond annotations, such as account requirements, type-specific params, delivery channel specifics (10/day SMS cap, webhook auto-disable after 10 consecutive failures), and the one-time return of webhook secret. No contradiction with annotations.

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

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

The description is somewhat long but well-structured with clear sections. It front-loads the purpose and provides dense, useful information without wasted words.

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

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

Given the complexity of the tool (3 params, nested objects, no output schema), the description is comprehensive. It covers prerequisites, type constraints, delivery behavior, and return value, leaving no major gaps for an agent.

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

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

Schema coverage is 100%, but the description adds extensive meaning with examples and constraints for each parameter, especially the type-specific params (e.g., 'sec_8k' with items codes) and delivery options (webhook signing details).

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

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

The description clearly states the tool 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 and unsubscribe by focusing on creation.

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

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

The description provides clear context for when to use the tool (to create a subscription) and notes prerequisites (requires Pipeworx OAuth account). It does not explicitly exclude alternatives, but the sibling tools list provides context.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false. The description adds that it returns category-bucketed example questions with exact tool+argument shape, which enriches understanding without contradicting annotations.

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

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

The description is front-loaded with common user queries and is well-structured. It is slightly long but every sentence earns its place, making it effective without being overly verbose.

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 one optional parameter and no output schema, the description fully explains the return format (category-bucketed examples) and usage scenarios. It also ties into the broader tool ecosystem, providing a complete picture 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 parameter description listing values. The description adds a list of possible focus areas (finance, pharma, etc.) and clarifies that omitting topic yields a cross-category spread, providing extra context beyond the schema.

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

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

The description clearly states the tool returns category-bucketed example questions for onboarding. It uses specific verbs like 'returns' and 'call' and distinguishes from siblings like ask_pipeworx (which answers questions) by positioning itself as a discovery tool.

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

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

Explicitly says 'Use this FIRST when you do not yet know what Pipeworx can do' and provides details on calling with no arguments for full spread or with a topic for focus. It also mentions learning how to call meta-tools, giving clear context.

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

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

The description goes beyond annotations by explaining that the row is deactivated (not deleted) and that historical events remain available via recent_alerts. This provides critical behavioral context beyond the non-destructive hint.

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, front-loaded with the action, and every sentence adds distinct value. 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 simple tool with one parameter and no output schema, the description fully explains the effect (deactivation) and consequence (historical events preserved), leaving no ambiguity.

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 a clear description for the 'id' parameter, and the tool description does not add additional semantic information beyond the schema. With 100% schema coverage, the baseline of 3 is appropriate.

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

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

The description clearly states the action ('Cancel a subscription by id'), specifies the resource (subscriptions), and distinguishes from subscribe by noting ownership enforcement and deactivation vs deletion.

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

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

The description explicitly states that ownership is enforced (only cancel own subscriptions), guiding appropriate use. It also implies when not to use (if permanent deletion is needed, though not explicitly stated), but lacks explicit 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?

Description goes beyond annotations (readOnlyHint, idempotentHint) by detailing internal workflow (NL parsing → entity resolution → data lookup → numeric comparison) and return format (verdict, structured form, actual value with citation, percent delta). 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 front-loaded with trigger phrases and purpose, then details scope and return. It is slightly verbose but each sentence adds value (usage context, supported domain, efficiency note).

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

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

For a complex NL verification tool with one parameter, no output schema, and comprehensive annotations, the description fully covers supported domain, return format, and internal process. It is complete for agent invocation.

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

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

Schema covers the single parameter with a description, achieving 100% coverage. Description does not add syntax or format details beyond the schema, meeting the baseline expectation.

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 defines the tool as natural-language claim verification against authoritative sources, specifically company-financial claims. It lists trigger phrases (e.g., 'Is it true that', 'fact check') and distinguishes from multi-step alternatives. This provides a specific verb-resource pairing and differentiates from sibling tools.

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

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

States 'Use whenever the agent needs to check whether something a user said is factually correct' and specifies the current scope (company-financial). While it doesn't explicitly list when not to use or alternative tools, the context is clear and sufficient 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.