Data Cambridge

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

Annotations already declare readOnly, openWorld, idempotent, non-destructive. Description adds cost model (free vs. BYO key) and return structure (per-model fields), greatly enhancing transparency.

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

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

Single paragraph, front-loaded with action and purpose, no fluff. 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?

With 4 parameters, no output schema but rich annotations, the description fully covers input semantics and expected output fields, making it 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?

100% schema coverage; description adds context: default model model details, API key purpose, and disambiguation for context. Goes beyond schema to explain usage nuances.

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?

Clear verb 'Probe' + resource 'LLMs' + outcome 'score visibility 0-100 per model'. Distinguishes from siblings like ask_pipeworx by focusing on visibility across multiple LLMs.

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

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

Explicit use cases: 'AI-marketing audits, pre-launch brand checks, competitive monitoring'. Explains default vs. optional Anthropic model but doesn't exclude alternatives explicitly; still clear.

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

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

Annotations already provide readOnlyHint/openWorldHint/idempotentHint. The description adds behavioral details: routing across 5,743 tools, filling arguments, returning structured answers with citation URIs, works on every tier, one fast call. No contradiction; the description complements annotations without duplicating them.

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

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

The description is longer than typical but front-loads like an instruction: 'PREFER OVER WEB SEARCH' first, then scope, examples, and escalation paths. Nearly every sentence earns its place; slight redundancy around being the default entry point. Not a tight two-liner, but well-organized.

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

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

Given the tool's complexity and no output schema, the description covers what it does, how it returns results (structured answer + citation URIs), when to use it, and when to use alternatives. Examples cover the domain range. Nothing an agent needs to choose this tool correctly is missing.

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

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

Schema description coverage is 100%, with the question parameter and all aliases fully documented. The description's examples ('current US unemployment rate', 'Apple's latest 10-K') illustrate acceptable inputs but don't add meaning beyond the schema. Baseline 3 is appropriate.

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

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

States a specific verb and resource: 'Routes the question to the right one of 5,743 tools across 1500 verified sources, fills arguments, returns the structured answer with stable pipeworx:// citation URIs.' Distinguishes itself from web search and names sibling tools it is not (ask_pipeworx_grounded, 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?

Explicitly says when to use: 'PREFER OVER WEB SEARCH', 'Use whenever the user asks...', and 'START HERE for most questions — this is the default entry point.' Also gives when-not-to-use and alternatives: step up to ask_pipeworx_grounded for verbatim evidence + confidence, deep_research for broad/multi-part questions.

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 establish read-only, idempotent, non-destructive behavior, and the description adds valuable context beyond that: beta routing candidates are toggled live, none is currently active, the tool currently matches ask_pipeworx, and there is no fallback to another router. This fully explains the experimental nature and current behavior.

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

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

The description is moderately detailed but every sentence adds information: beta status, identical scope, current experimental state, use instructions, and no-fallback clarification. It is slightly longer than strictly necessary but not wasteful.

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 single-parameter tool with no output schema, the description is complete: it states what the tool is, how to use it, what it currently does, how it compares to the stable sibling, and that it is a fully working router. An agent has enough context to select and invoke it correctly.

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

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

Schema description coverage is 100%, and the schema itself fully documents the question parameter plus all five aliases. The description does not add parameter-level meaning, but the baseline of 3 is appropriate because the schema carries the burden.

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

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

The description clearly identifies the tool as a beta version of ask_pipeworx and as an identical universal router with the same tools, arguments, and response shape. It distinguishes itself from siblings by naming ask_pipeworx and explaining the experimental routing difference.

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 explicitly tells the agent to use this tool exactly like ask_pipeworx when the newest routing is desired, and it names the stable alternative. It also clarifies the current state (no active candidate) and that results are compared against the stable router, giving concrete selection guidance.

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

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

The description goes well beyond the readOnly/openWorld/idempotent annotations by specifying the exact success payload shape and the enumerated refusal reasons. It also discloses that answers are extracted only from the tool result and that the tool costs an extra LLM call. This gives the agent a realistic model of behavior without any 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 dense and front-loaded with the core purpose and differentiator. It is somewhat verbose with long parenthetical lists, but every sentence contributes either routing, return contract, or selection guidance. It could be tightened without losing value, but it is far from bloated.

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?

Even without an output schema, the description fully specifies the return envelope and all failure modes, which is the most important missing context. It also provides sibling differentiation, cost tradeoffs, and explicit use cases, making the tool safe to invoke with minimal 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?

All six parameters are aliases for the same natural-language question, and the schema documents them with 100% coverage. The description adds no parameter-level semantics, but that is acceptable because the schema already carries the full burden. 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 identifies the tool as a hallucination-resistant answer mode for high-stakes reads and immediately distinguishes it from ask_pipeworx. It specifies what it does: routes to a tool, fetches data, then extracts the answer only from the tool result. This gives the agent a precise, distinctive purpose.

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

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

The description explicitly states when to use the tool: 'whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts.' It also says when not to use it: 'prefer ask_pipeworx for casual lookups,' and gives the cost rationale (one extra LLM call). This is clear, actionable routing 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?

Extremely detailed about behavior: resolver contract, parent event extraction, news fallback fields, safety short-circuits for low-confidence or closed markets, wide-spread warnings, and cancellation rule parsing. Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint, and the description adds rich context beyond these.

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

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

Front-loaded purpose but very lengthy with extensive detail. While well-structured with section headers (RESPONSE SHAPES, RESOLVER CONTRACT), it contains more than necessary for a concise 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?

Given no output schema, the description thoroughly explains return structure, edge cases (low match confidence, closed markets, wide spreads), and resolution rules. All three parameters are well-defined with examples.

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

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

Schema coverage is 100%, and the description adds meaning: explains depth values ('quick = 2-3 sources'), include_raw effect (summarization vs full payload), and market input formats. Adds value beyond schema.

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

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

The description clearly states the tool researches a Polymarket bet by pulling Pipeworx data, supporting multiple input formats (slug, URL, question text). It lists classifiers and distinguishes itself from siblings like polymarket_arbitrage and polymarket_edges by focusing on data gathering for 'should I bet on X' scenarios.

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

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

Provides explicit use cases ('should I bet on X', 'what does the data say about Y') and examples. Lacks explicit when-not-to-use guidance but the context of sibling tools (e.g., polymarket_edges) implicitly covers alternatives.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive. The description adds value by specifying the data source (data.cambridgema.gov) and the return contents, 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?

Two concise sentences, front-loaded with action and source. Every word contributes, 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?

No output schema is present, but the description adequately summarizes return fields (names, descriptions, resource IDs) and links to the related tool. Given the tool's simplicity and full annotation coverage, it 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?

With 100% schema description coverage, the schema already explains parameters. The description adds context about the 'query' parameter (keyword search) and return usage, but doesn't significantly deepen parameter 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?

The description clearly states the action (search) and the resource (Cambridge open-data catalogue), specifies output (dataset names, descriptions, Socrata resource ids), and distinguishes from sibling tools like cambridge_query by indicating the output is meant for use with that 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 indicates when to use (searching by keyword) and how the result feeds into cambridge_query, but lacks explicit exclusions or alternative tool recommendations. Context from sibling names helps but isn't explicit in the description.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true. The description adds transparency by explaining the optional _apiKey parameter and mentioning the keyless endpoint, which is behavioral context beyond the 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?

The description is three sentences with no wasted words. The first sentence front-loads the core action and resource. The second sentence succinctly lists the SoQL clauses. The third sentence directs to sibling tools. 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 8 parameters with full schema coverage and no output schema, the description provides enough context for an agent to use the tool. It explains the query capability, the resource identifier method, and how to obtain parameters. While it lacks an explicit mention of the output format (which is standard Socrata JSON), it is still reasonably complete for the 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 description coverage is 100%, so the baseline is 3. The description does not add significant new meaning per parameter; it merely enumerates the SoQL clauses. However, the overall context of 'Full SoQL' helps the agent understand the parameters collectively. This meets the minimum but does not exceed it.

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

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

The description clearly states the verb ('Run a raw SoQL query'), the specific resource ('any Cambridge open-data resource'), and the identifier method ('Socrata id'). It also distinguishes itself from sibling tools 'cambridge_datasets' (for finding resource ids) and 'cambridge_recent' (for common ones).

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 this tool (when you have a Socrata id and want to run a raw query) and when to use alternatives ('Use cambridge_datasets to find a resource id, or cambridge_recent for the common ones'). It also lists the SoQL clauses available, guiding the agent on how to structure queries.

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

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

Annotations already mark readOnly, idempotent, nondestructive. Description adds ordering ('newest-first') and that a where clause can filter, supplementing the annotation coverage well.

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?

Compact but information-dense: usage guidance, dataset list, ordering, filtering advice, and alternative in few sentences, front-loaded.

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

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

Given the tool's simplicity (no output schema, simple params), the description fully covers use cases, datasets, filtering, ordering, and alternative tools.

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

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

Schema coverage is 100% (baseline 3). Description adds concrete dataset names and explains the where parameter's purpose, improving clarity beyond schema.

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

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

The description clearly states the tool retrieves recent records from Cambridge open datasets by friendly name, lists the three datasets, and distinguishes from sibling tools like cambridge_query and web search.

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 recommends use over web search for specific queries, says to use cambridge_query for anything else, and mentions adding SoQL where clauses for filtering.

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, indicating safe, non-destructive, repeatable behavior. The description adds value by detailing how off-calendar fiscal years are handled, the inclusion of citation URIs, and efficiency gains (replaces 8-15 sequential lookups). 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 moderately lengthy but front-loaded with natural-language triggers. Every sentence adds meaningful context (data sources, sorting, efficiency). A slight reduction in redundant phrasing (e.g., 'side-by-side... in ONE parallel call' could be tightened) would improve conciseness.

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

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

Despite lacking an output schema, the description fully covers return format (paired data + citation URIs, sorted by primary metric) and data provenance. It addresses behavioral nuances like fiscal-year handling and explicitly states the tool's efficiency advantage, making it fully self-contained for an AI agent.

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

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

Schema coverage is 100%. The description reinforces parameter meaning: for 'type' it specifies data sources (SEC EDGAR/XBRL for company, FAERS/FDA/clinicaltrials.gov for drug); for 'values' it clarifies required format (tickers/CIKs vs. drug names) and the 2-5 item limit. This adds real context beyond the raw schema.

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

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

The description begins with concrete example queries like 'Compare X and Y' and 'rank these companies,' directly stating the tool is for side-by-side comparison of 2-5 companies or drugs. It clearly differentiates from siblings such as entity_profile by emphasizing parallel evaluation over sequential lookups.

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

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

The description includes an explicit directive: 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.' It also clarifies when to use each data type and notes that results are sorted by primary metric, guiding the agent on how to interpret output for queries like 'largest.'

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 safety profile is covered structurally. The description adds genuinely new behavioral insight: parallel decomposition into facets, verbatim evidence + confidence + source, gaps[] for unanswered facets, contradictions[] on certain depths, semantic excerpting, expected 15-90s latency, and the caveat that citations are only present when the source record is actually fetchable. That is substantial value beyond the annotations.

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

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

The description is dense and front-loaded with the most critical caveat (account required; fallback). But it is long and somewhat rambling — a paragraph of caveats and clarifications that could be tightened. It earns its place for the most part, but loses a point to over-length and occasional redundancy (e.g., explaining 'NOT open-web search' twice in different 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?

Context is complex: a paid-tier gating constraint, a clear fallback alternative, latency expectations, output shape (findings packet with gaps, contradictions, citation URIs), and critical failure semantics (empty gaps[] when topic isn't in catalog). The description addresses all of these. The only notable gap is that it never explicitly states that 'quick' skips the contradictions[] scan — implied by the depth parameter description but not spelled out in the main description. Given the output schema is absent, the description still does enough to let an agent call it 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%, and the description adds enrichments: it explains what 'quick/standard/thorough' actually do in behavioral terms (gap recovery, contradiction scan, paid tier) and clarifies that 'question' can be broad/multi-part. However, much of this repeats or closely restates what the parameter descriptions already provide. The baseline of 3 is appropriate since the schema already carries the load.

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

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

The description states a specific verb ('researches'), a precise resource (Pipeworx's 1500 structured data sources), and clarifies a critical boundary — this is 'NOT open-web search.' It also names the key distinction from the closest sibling (ask_pipeworx), so an agent can discriminate without opening schemas.

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 explicit when-to-use ('best for broad/multi-part questions over structured data'), explicit when-not-to-use ('single lookup', 'BREAKING or colloquial CURRENT-NEWS' — prefer ask_pipeworx), and even names the alternative tool. That satisfies the full usage-guidance test.

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

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

Annotations already indicate readOnly, idempotent, non-destructive. Description adds that results are ready to call directly without extra schema lookup, and returns top-N relevant tools. 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?

Description is two sentences, front-loaded with purpose, uses a list of domains without verbosity. Every sentence contributes 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 discovery tool, the description explains return content (names, descriptions, schemas with examples) and when to use. No output schema exists, but the description implies the output format is sufficient for direct 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 detailed descriptions for each parameter. The description adds minimal extra context (e.g., 'top-N' implies 'limit') but nothing beyond what the schema already conveys. 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 finds tools by describing data or task, uses a specific verb ('find'), and distinguishes from siblings by being a meta-discover tool that returns other tools.

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

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

Explicitly advises to call this first when many tools are available, and provides example use cases like 'analyze housing market trends'. It implicitly says not to use if already certain which 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, openWorldHint, idempotentHint, and destructiveHint:false. The description adds substantial behavioral context: it lists all fan-out sources, explains that USPTO patents soft-fail after May 2025, clarifies that empty sections are valid 'no data' results, documents the resolved:false behavior for private companies, and exposes sources_used/sources_failed semantics. This goes well beyond the annotations and prepares the agent for unusual outcomes.

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 and dense, but nearly every clause carries information: return sections, source names, failure behavior, and input forms. It is front-loaded with user intents and the 'ALWAYS PREFER' guidance. Some structure — bullet points or section breaks — would improve scannability, but the density is justified by the tool's breadth.

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

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

With no output schema, the description carries the full burden of explaining return values, and it does so exhaustively: it names every return section (cik, recent_filings, fundamentals, patents, federal_contracts, fda_products, hiring, news, LEI, sources_used/sources_failed), explains expected empty sections, documents URI formats, and specifies behavior for private companies and interchangeable parameter types. Nothing needed to invoke this tool correctly is missing.

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

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

Schema description coverage is 100%, and both parameters are richly documented in the schema itself: type explains that 'company' and 'ticker' behave identically, and value already gives examples of ticker, CIK, and company name. The description reinforces these with concrete examples ('AAPL', '0000320193', 'Moderna') but adds little beyond the schema. Baseline 3 is appropriate.

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

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

The description states a specific verb ('profile', 'brief', 'research') and a concrete resource: a US public company identified by ticker, CIK, or name. It clearly differentiates this tool from simpler SEC/XBRL/news lookups by emphasizing 'full cross-source profile in ONE parallel call.' Even without naming specific siblings, an agent can infer that this is the holistic-company-overview 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 explicitly says 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view' and gives concrete user-intent triggers ('tell me about X', 'research Acme', 'brief me on Tesla'). It even notes the private-company edge case where the tool returns resolved:false with a notes line. It does not name specific sibling alternatives like compare_entities or resolve_entity, but the guidance is otherwise clear.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true. The description adds context about clearing sensitive data but does not disclose additional behavioral traits beyond what annotations provide. 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?

Two concise sentences, front-loaded with the action, followed by usage guidance. Every word earns its place 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?

For a simple one-parameter destructive tool with annotations, the description covers purpose, usage, and pairing. It lacks return value details but no output schema exists. Adequately complete for the 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?

The schema already describes the 'key' parameter with 100% coverage. The description only mentions 'by key', adding no new meaning beyond the schema. Baseline is 3.

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 deletes a memory by key, using specific verbs and resource. It distinguishes from siblings by mentioning pairing with 'remember' and 'recall', making the deletion 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 provides explicit usage scenarios (stale context, task done, clear sensitive data) but does not explicitly name alternatives or contraindications. However, given the tool's specific operation, the guidance is clear and useful.

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. Description adds that it fetches the page, extracts title/description/links, and emits standard markdown format, providing behavioral context beyond the annotations without contradiction.

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

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

Description is one paragraph of three sentences, front-loaded with the main action. Could be slightly more concise, but all information is relevant and no filler.

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

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

No output schema exists, but description adequately explains output as a single markdown text blob ready for placement. Combined with rich annotations, the description provides sufficient context for the tool's behavior and output.

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

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

Schema coverage is 100% and already describes both parameters well. The description does not add new parameter-specific details, so baseline 3 is appropriate. It adds output context but not parameter semantics.

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

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

Description clearly states the tool generates an llms.txt file for any URL, specifies the output format, and lists concrete use cases. It distinguishes itself from siblings by being a unique content generation tool, not overlapping with any other listed sibling.

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 (client indexing, own project, competitor auditing), providing clear context for when to use. Does not explicitly mention when not to use or alternatives, but the context is sufficient.

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

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

Annotations already provide readOnlyHint, destructiveHint, etc. Description adds that listing defaults to active subscriptions and mentions the include_inactive parameter, which is useful beyond annotations.

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

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

Two sentences, front-loaded with purpose, 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?

Tool is simple with one optional param. Description lists return fields and provides usage guidance, sufficient for selection and invocation despite no output schema.

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

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

Schema covers 100% of the single parameter with description. Description adds context about default behavior (active only) 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?

States 'List the caller's active subscriptions' with specific verb and resource, and lists return fields. Clearly distinguishes from sibling tools like subscribe/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?

Explicitly says 'Use this to review what you're monitoring before adding more or to find an id to cancel', providing clear when-to-use context and implying 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?

Even though annotations are only negative hints, the description adds meaningful behavioral details: rate-limited to 5 per identifier per day, free, does not count against quota, returns a claim_token, and reading later reports status/changes. 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 longer than typical but each sentence adds necessary context (usage exclusions, token behavior, rate limits, quota impact). It front-loads the core purpose, though the later motivational sentence about roadmap could be trimmed.

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

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

With no output schema, the description still explains the return token and how to read later status/changes. It covers all relevant use cases, exclusions, limits, and parameter semantics, making the tool fully self-contained 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 already covers all 4 parameters, so baseline is 3. The description adds extra value by explaining how to use claim_token, advising not to paste user prompts, and suggesting message length. This goes beyond the schema's field descriptions.

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

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

Description opens with 'Tell the Pipeworx team something is broken, missing, or needs to exist' — a specific verb and resource. It clearly distinguishes this as feedback tooling for Pipeworx tools, which none of the sibling tools handle.

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...') and when not to ('if the tool came from a different MCP server... file it with that server instead'). Also clarifies the claim_token workflow for follow-up.

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 specifying it is self-aggregating, cached 5min-1h, and derived from CF analytics-engine with no PII. No contradictions.

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

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

Three sentences plus three bullet points, efficiently front-loaded with purpose, then use cases, then notes. No wasted words.

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

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

With no output schema, the description mentions return values (top tools, packs, total volume) and window options. It lacks explicit output format but is sufficiently complete for a simple tool with one parameter.

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

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

Schema coverage is 100% and already describes the enum parameter well. The description adds nuance about window behavior but does not significantly extend beyond schema 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 it returns top tools, top packs, and total call volume, using specific verbs and naming the resource. It distinguishes from sibling tools like ask_pipeworx and discover_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?

The description lists three explicit use cases (discovering hot data, confirming canonical tools, aligning use case) and explains window options. However, it does not explicitly state when not to use or mention alternatives.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds rich behavioral context: scanning process, Jaccard similarity threshold, placeholder filtering, fill check against live CLOB depth, and response structure. No contradictions.

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

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

Long but well-structured with clear sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK). Front-loaded with purpose and modes. Every sentence adds necessary detail for correct tool invocation and interpretation of results.

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 return values: opportunities[] with fields and partition_check for event mode. Covers edge cases like skipped_low_similarity and placeholder filtering. Complete for a complex arbitrage detection 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?

Input schema has 100% coverage for both parameters. The description adds significant meaning beyond the schema: explains event mode slugs, topic mode seed questions, and notes that full Polymarket URLs are accepted for the event parameter. Provides concrete examples.

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

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

Clearly states it finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. Distinguishes itself from sibling tools like polymarket_edges and polymarket_fill_risk by explaining its role and referring to polymarket_fill_risk for custom sizing.

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

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

Explicitly describes when to use no args (trending scan), event mode (specific market), and topic mode (cross-event scan). Provides rationale for each mode and warns against trading when fill check shows realizable edge ≤ 0. Also directs to polymarket_fill_risk for custom sizing.

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, confirming safety. The description adds extensive detail: caching (1h KV), model families, response segments (by_segment), diagnostic fields, and tradeable-edge knobs. 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 overly verbose, spanning multiple paragraphs with detailed model family explanations and response structure. While informative, it could be condensed. The front-loading of purpose helps, but the bulk of text may overwhelm agents.

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 (3 model families, 9 parameters, no output schema), the description is highly complete. It explains return structure (by_segment), diagnostics, caching, and knob effects, covering all necessary context for an agent to use 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% with parameter descriptions. The description adds context beyond schema, explaining how knobs like min_liquidity and max_spread_pp act as tradeable-edge filters and how min_partition_leg_kelly applies differently. This adds value but is not essential since schema already covers basic meaning.

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

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

The description clearly states 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price,' using a specific verb-resource combination. It distinguishes itself from siblings like polymarket_arbitrage and polymarket_edge_tracker by focusing on disagreement-based opportunity discovery for daily betting.

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 it is 'Built for "what should I bet on today" — agents discover opportunities without paging hundreds of markets,' indicating when to use it. However, it does not explicitly exclude alternatives or provide when-not-to-use guidance, though the sibling context implies differentiation.

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 non-destructive. The description adds extensive behavioral details: return structure (tracked, expired, snapshot_dates), field meanings (trend, decay_pp_per_day, lifespan_days), data limitations (60-day TTL, gaps when snapshots not written), and computation basis (daily closes, not intraday). No contradiction with annotations.

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

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

The description is lengthy and includes detailed explanations of response fields. While front-loaded with the core question, the extensive field documentation could be more concise or structured. It serves its purpose but could be streamlined.

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 covers return values (tracked, expired, snapshot_dates) and their fields (trend, decay_pp_per_day, lifespan_days). It also addresses data limitations (TTL, gaps) and parameter defaults. With 100% schema coverage and rich behavioral context, the description is complete for an agent to understand and use the tool.

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

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

Schema coverage is 100%: both parameters (days, window) are described in the input schema. The description adds default values and slightly more context (e.g., window options: '24hr | 1wk | 1mo'), but overall adds minimal meaning beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly communicates the tool's purpose: tracking edge persistence and decay from daily snapshots, answering 'how long has this edge existed and is it shrinking?' However, it does not explicitly distinguish this tool from sibling tools like polymarket_edges (current edges) or polymarket_arbitrage, slightly reducing clarity for an agent choosing among them.

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

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

The description implies usage for historical edge analysis and provides context (e.g., 'a 3-week-old wide edge is wide for a reason'), but does not explicitly state when to use this vs. alternatives or when not to use it. No exclusions or alternative tool references are given.

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

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

Annotations already declare readOnlyHint=true, but the description goes further: details the ladder walk, specific return fields (top_of_book, slippage, etc.), basket mechanics, and warns about thin legs and forced directional risk. No contradictions with annotations.

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

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

The description is dense but well-organized with clear sections for single-market and basket modes. Every sentence provides useful information, though the length is necessary for the complexity. Could benefit from slightly more compact phrasing.

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 documents return values for both modes, including edge cases like thin legs and forced directional risk. Schema coverage is 100%, and the description is exhaustive for a complex tool.

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

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

Schema coverage is 100%, but the description adds significant value by explaining how each parameter behaves in single-market vs basket mode (e.g., side defaults for each mode, size_usd interpretation as max spend vs settlement notional).

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 checks realizable vs theoretical edge against live order-book depth, and distinguishes between single-market and basket modes. It explicitly references sibling tools (polymarket_arbitrage, polymarket_edges) and explains when to use this tool before them.

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

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

Explicitly states 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. Provides context on why (thin books, partial fills causing directional risk) and implies when not needed (small trades).

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds substantial behavior beyond that: it discloses matching limitations (token-overlap, keyword matching), safety fields that can be non-empty even when pairs exist, gross vs net fees (fees_note), the fact that unknown legs are never paired, and skipped-comparison counters. This is far more transparency than the annotations alone provide.

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

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

The description is long but well-structured, with clearly labeled sections (TWO MODES, RESPONSE, SAFETY FIELDS, Codes) and the core purpose front-loaded in the first sentence. Every sentence adds edge-case value, though the detailed enumeration of compatibility codes could be tightened or moved to a reference, making the overall length slightly above the minimum needed.

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

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

With no output schema, the description thoroughly documents the response shape (leg-by-leg prices, spread[].top_spreads_pp, skipped_unclassified, low_confidence_pairs) and every relevant flag, code, and caveat. It also warns that compatibility_warning can appear even when matched_pairs>0 and that temporal_alignment null means 'could not compute' rather than aligned, covering scenarios that would otherwise cause misinterpretation.

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 each parameter is already described, but the description adds meaningful semantics: topic is a pre-mapped shortcut with exactly 10 listed options, while kalshi_event_ticker and polymarket_event_slug override the topic-mapped side. It also clarifies that both modes run the same overlap matcher, which prevents a user from assuming explicit mode behaves differently.

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?

States a specific verb and resource: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It clearly differentiates from siblings like polymarket_arbitrage and polymarket_edges by naming both venues and the spread focus, and it explains the signal's meaning (delta is real when bet shapes are equivalent). The title and description align with the tool name.

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 details two modes (topic shortcuts vs explicit ticker/slug) and when each is appropriate, and it includes critical guidance that pre-mapped topics often return compatibility_warning, so they are not directly tradeable. It does not name alternative tools or give explicit 'use this instead of X' exclusions, but the context is clear enough for an agent to select this tool correctly.

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. The description adds valuable context beyond annotations: the scoping to an identifier (anonymous IP, BYO key hash, or account ID) and the behavior of omitting key to list all keys. 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?

Two sentences, each serving a distinct purpose: the first states core action, the second provides usage context and pairing. No wasted words, well-structured and front-loaded.

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

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

Given the tool's simplicity (one optional parameter, strong annotations, no output schema), the description is complete. It covers purpose, behavioral details, scoping, and relation 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 coverage is 100%, baseline is 3. The description adds meaning by explaining the effect of omitting the key ('list all saved keys') and providing examples of usage. This compensates beyond the schema description.

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

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

The description explicitly states the verb 'retrieve' and the resource 'value previously saved via remember', and distinguishes between single-key retrieval and listing all keys. It clearly differentiates from siblings like 'remember' and 'forget'.

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

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

The description provides clear guidance on when to use the tool ('look up context the agent stored earlier... without re-deriving it from scratch') and mentions pairing with 'remember' and 'forget'. However, it does not explicitly state when not to use it or exclude specific alternatives.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false. The description adds useful behavioral details (e.g., mark_read behavior, persistence of feed) without contradicting annotations. No rate limit or pagination info, but acceptable given annotation coverage.

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 pack key information: purpose, return fields, filters, mark_read flag, and alternative access method. 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 5 optional parameters and no output schema, the description covers purpose, filters, return fields, and access patterns. Could mention pagination or sorting, but openWorldHint reduces need for exhaustive detail.

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 five parameters are described in the schema (100% coverage), and the description adds real-world examples (e.g., 'sec_8k') and explains the semantic effect of mark_read. Adds value beyond the schema alone.

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

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

The description uses a specific verb ('Pull fired events') and clearly identifies the resource ('subscription feed'). It distinguishes from siblings like list_subscriptions by explicitly stating it returns alert events, not subscription metadata.

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

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

Provides context that polling works and mentions an alternative HTTP endpoint for scripts/dashboards. Does not explicitly state when not to use or compare to siblings, but the guidance is clear enough for typical 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?

Beyond the annotations (readOnlyHint, idempotentHint), the description details the underlying sources (SEC EDGAR, GDELT→GNews fallback, USPTO), specifies that USPTO soft-fails until reactivated, and describes the return structure (changes[] grouped by source + total_changes count + citation URIs). No contradictions with annotations.

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

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

Despite covering multiple sources and edge cases, the description is tightly written. It front-loads common query patterns, then succinctly explains the fan-out, parameter syntax, and when to use an alternative. No redundant sentences.

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 is complex (multi-source, fallback, soft-fail, relative dates), but the description covers all critical aspects: supported sources, parameter formats, return structure, and comparison with entity_profile. No output schema exists, but the description adequately describes the return format.

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

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

Schema coverage is 100%, so baseline is 3. The description adds useful context: examples of relative shorthand for 'since' (7d, 30d, 3m, 1y) and that 'value' accepts ticker or CIK. It also reiterates the enum restriction for 'type'. This adds value beyond the schema.

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

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

The description starts with concrete query examples ('What's new with X', 'latest on Y'), then states precisely: 'change feed for a company in the last N days/weeks/months in ONE parallel call.' It explicitly 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 explicit when-to-use examples, recommends a typical 'since' value ('30d' or '1m'), explains fallback behavior, and directly tells the agent when to use an alternative ('Use entity_profile instead when you want the static profile').

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

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

Annotations declare idempotentHint=true and destructiveHint=false; the description adds meaningful context about persistence (authenticated vs anonymous sessions, 24-hour retention for anonymous). 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?

Four sentences in a concise paragraph with no wasted words. Front-loaded with the core purpose, then usage, then behavioral details. 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 the tool's simplicity (2 required params, no output schema, clear annotations), the description covers all aspects: purpose, when to use, behavioral traits (persistence), and sibling context. 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 already covers both parameters with clear descriptions (e.g., 'Memory key' with examples). The description adds context like 'scoped by your identifier' and reiterates allowed values for value field, but schema coverage is 100%, so a slight bonus for supplementary guidance.

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

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

The description uses specific verbs ('save', 'reuse', 'store') and clearly identifies the resource as key-value memory. It distinguishes from siblings by naming 'recall' and 'forget' as paired tools, and provides concrete examples like 'resolved ticker, target address, user preference'.

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 ('discover something worth carrying forward') and provides guidance on pairing ('Pair with recall to retrieve later, forget to delete'). No ambiguity about context or 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?

Even though annotations already declare readOnly, idempotent, openWorld, and non-destructive hints, the description adds substantial operational detail: cross-source identity spine, graceful degradation when GLEIF/OpenFIGI is down, explicit `unresolved` reporting, `figi_candidates` disambiguation, and source-labelled identifiers. This goes far beyond what annotations convey.

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

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

The description is information-dense but not concise; the opening sentence is a long, repetitive list of example queries, and the body is a stream-of-consciousness paragraph with a massive parenthetical. Every sentence carries value, but the structure could be split into scannable sections without losing content.

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

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

With no output schema, the description compensates by covering key response behaviors: `figi_candidates` on ambiguous matches, `unresolved` for failed lookups, source labelling, and fallback behavior. It does not fully specify the JSON response shape, but the essential success and failure modes are documented clearly enough for an agent to invoke and interpret the tool.

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

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

Schema coverage is 100%, but the description enriches both parameters significantly. For `value`, it defines accepted input formats (ticker, CIK, ISIN, name, brand/generic) and provides a critical anti-pattern: never pass the full noun phrase, only the issuer name. For `type`, it explains the return semantics of each enum value, including non-equity instrument resolution.

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

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

The description states a highly specific verb and resource: 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input.' It also differentiates from siblings by commanding 'Use FIRST whenever you have a name but need an ID,' which makes the tool's scope 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?

Explicit when-to-use guidance is provided via 'Use FIRST whenever you have a name but need an ID' and the note that it replaces 2-3 manual lookups. It does not explicitly name alternative tools for other intents, but the priority instruction plus clear scope is sufficient for an agent to route correctly.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint true and destructiveHint false. The description adds significant behavioral context: internally calls ai_visibility_check per entity, ranks results, and returns a ranked list with score, confidence, signal density. This goes well beyond annotations, explaining the tool's internal logic and output structure.

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

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

The description is two sentences: first sentence states the core action, second elaborates on process and use case. It is front-loaded with the main verb and resource, and every sentence adds essential information 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?

The description explains the complete workflow (probes, ranks, lists) and the return format (ranked list with score, confidence, signal density). Despite no output schema, the description covers all needed information for an agent to understand inputs and outputs. Annotations further reinforce safety and idempotency.

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

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

Schema description coverage is 100%, so the schema already fully documents all parameters. The description adds value by explaining how parameters interact (e.g., first entity is the subject, how _apiKey is used, context applied to all probes) and the overall workflow.

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

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

The description clearly states the tool compares AI visibility across multiple entities side-by-side, specifying the action (probe, rank, surface). It distinguishes from sibling tools like ai_visibility_check (single entity) and compare_entities (general comparison) by focusing on AI presence and ranking. The example query 'does Claude know about us as well as our competitors?' reinforces the purpose.

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

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

The description provides clear context: 'Useful for competitive AI-marketing audits' with an example. It implies when to use (for multi-entity comparison) versus single-entity checks via ai_visibility_check, but does not explicitly state exclusions or 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?

Discloses potential 5-30s delay on first bundlephobia measurement and graceful degradation with 'sources_failed' list. Annotations (readOnly, idempotent) are consistent and supplemented.

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

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

Well-structured with main purpose first, then details. Slightly long but every sentence adds necessary information for a composite tool.

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

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

Despite missing output schema, description fully documents return fields (summary block, per-advisory detail, links, alternative versions) and handles partial failures.

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. Description adds value by mentioning scoped package syntax and default behavior for 'version', 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?

The description clearly states the tool is a composite check for npm package viability, combining data from deps.dev and bundlephobia. It distinguishes itself by being a single-call aggregation, making it unique among siblings.

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

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

Explicitly tells when to use: 'whenever an agent asks "is X safe / popular / small"' and provides scope boundaries (NPM only for v1) with alternatives for other ecosystems.

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?

While annotations already declare readOnlyHint, idempotentHint, and destructiveHint, the description adds significant behavioral details: embedding model (BGE-base-en), similarity metric (cosine), window size (500-char overlapping), character cap (200K), truncation behavior, and that passages include offsets for verification. No contradictions.

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

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

Four sentences, each with distinct value: purpose, usage guideline, pairing advice, and technical details. No redundant words; every sentence earns its place.

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

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

No output schema exists, so description fully explains return: top-N passages with character offsets and similarity scores. Also covers cap and truncation flag. Complete for a search tool.

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

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

Schema coverage is 100%, so baseline is 3. But description adds meaningful examples for 'query' (e.g., 'supply-chain risk'), clarifies 'text' max length, and explains 'limit' default and range. This goes beyond the schema's basic descriptions.

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

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

The description clearly states 'Semantic search INSIDE a fetched record' and provides concrete examples like SEC 10-K and articles. It distinguishes itself from fetching the whole document and pairs with 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?

Explicitly says 'Use when the record is too big to cram into the prompt' and mentions pairing with ask_pipeworx_grounded. Provides clear context for when to use vs alternatives.

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

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

The description adds behavioral details like delivery channel limitations (10 SMS/day, webhook auto-disable), but contradicts the idempotentHint annotation (description implies each call creates a new subscription, annotation claims idempotency). Without the contradiction, would be higher.

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 purpose upfront, followed by types and delivery details. While slightly lengthy, each sentence adds value and there is 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?

For a complex tool with multiple subscription types and delivery options, the description is thorough, covering OAuth requirement, type-specific filters, delivery channels, rate limits, webhook signing, and return value. No output schema needed as return is simple.

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. The description adds significant meaning beyond the schema by explaining each subscription type's params in detail and delivery constraints (phone verification, rate limits).

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, distinguishes it from siblings like unsubscribe and list_subscriptions, and specifies the exact resource and action.

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

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

The description explains when to use the tool (to subscribe to alerts), prerequisites (Pipeworx OAuth account), and provides type-specific parameter guidance, but does not explicitly state when not to use it or compare to 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 readOnly, openWorld, idempotent, non-destructive. The description adds valuable context about the tool being an onboarding/discovery tool that returns example questions and tool call shapes, without repeating or contradicting annotations. Some behavioral details (e.g., return format) are helpful 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 well-structured, front-loaded with common phrasings, and clearly explains purpose, behavior, and invocation. It is slightly verbose with repeated phrases, but every sentence adds value. Good balance of detail and brevity.

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 low complexity (one optional parameter, no output schema) and rich annotations, the description thoroughly covers what the tool does, its return format, how to use it, and when to use it. No gaps are apparent.

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

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

Schema coverage is 100%, and the description of the 'topic' parameter is identical to the schema's description. No additional meaning or clarity is added over what the schema already provides. Baseline score of 3 applies.

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

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

The description clearly states the tool's purpose: onboarding entry point that returns category-bucketed example questions with exact tool calls, drawn from the live catalog. It distinguishes from siblings by recommending use 'FIRST' and explicitly naming meta-tools like ask_pipeworx, entity_profile, compare_entities.

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

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

Explicitly states call with no arguments for full spread, or pass topic for focus. Provides clear when-to-use guidance: 'when you do not yet know what Pipeworx can do for you' or 'to learn how to call the meta-tools'. Effectively differentiates using 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?

Discloses that the row is deactivated (not deleted) and historical events remain available via recent_alerts. Adds context beyond annotations (readOnlyHint=false, destructiveHint=false, idempotentHint=true).

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

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

Three sentences, front-loaded with action, no wasted words. Efficiently communicates purpose, constraints, and behavior.

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

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

Complete for a simple tool with one parameter and no output schema. Covers purpose, usage constraint, behavioral nuance, and implications for historical data.

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 description of the 'id' parameter. Description adds ownership enforcement but does not provide additional parameter details 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?

Clear verb+resource: 'Cancel a subscription by id.' Distinguishes from sibling tools like 'subscribe' (create) and 'list_subscriptions' (view).

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

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

States ownership enforcement ('you can only cancel your own subscriptions'), which guides when to use. No explicit alternatives or 'when not to use', but purpose is distinct enough.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds valuable operational detail beyond this: the SEC EDGAR + XBRL path for company financials, the fallback to a grounded pipeline, the full set of verdicts, and a prominent warning that 'could_not_verify means the check did not happen... not evidence for or against the claim.' This is rich, non-redundant behavioral context.

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

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

Although the description is longer than typical, every sentence serves a purpose: example queries front-load trigger conditions, the usage statement defines scope, the pipeline description clarifies behavior, the verdict list sets expectations, and the caveat about could_not_verify is critical. It is well-structured and dense without fluff, making it highly effective for agent selection and invocation.

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 has significant complexity (two execution paths, multiple verdicts, error semantics) and no output schema, so the description must cover return values. It does so thoroughly: lists all verdicts, mentions the actual value with citation and reasoning, and distinguishes 'could_not_verify' from 'unsupported.' This is complete enough for an agent to know exactly what to expect and how to interpret results.

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

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

Schema description coverage is 100% for both parameters (`claim` and `tolerance_pct`), so the schema already fully documents their meaning. The description adds minimal parameter-level detail beyond mentioning 'exact percent-delta math,' which does not clarify parameter formats or bounds. A baseline 3 is appropriate given the complete schema coverage.

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

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

The description explicitly states a specific verb+resource: 'natural-language claim verification against authoritative sources' and 'use whenever the agent needs to check whether something a user said is factually correct.' It opens with example user phrasings that clearly indicate the intended trigger, distinguishing it from general Q&A or research tools among siblings.

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

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

The description provides a clear usage criterion ('Use whenever the agent needs to check whether something a user said is factually correct') and explains the two execution paths (SEC EDGAR fast path vs. grounded pipeline). It mentions that the tool replaces 4–6 sequential calls, reinforcing consolidation. It does not explicitly name alternative tools or exclusions, but the scope is well-defined.

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