Data Cookcounty

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

Annotations already declare readOnlyHint and idempotentHint, so the safety profile is covered. The description adds behavioral context beyond that: it documents the default model, the fact that passing `_apiKey` triggers external Anthropic calls with direct billing to the user, and the return structure. This is meaningful extra disclosure without contradicting annotations.

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

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

The description is three sentences with no filler. It front-loads the core purpose first, then provides operational details (default model, key handling), and ends with return format and use cases. 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?

With no output schema, the description carries the burden of explaining return values, and it does so explicitly: 'Returns per-model {score, confidence, signals, raw_response} + a combined view.' It also covers optional parameters (models, _apiKey, context) and gives example entity values, making it sufficiently complete for an agent to invoke correctly.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds semantic value by clarifying the default model ('Workers AI Llama-3.3-70b (free)') and explaining that `_apiKey` is 'passed straight through to api.anthropic.com' with cost implications, which enriches understanding beyond the schema's basic 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?

The description opens with a specific verb 'Probe one or more LLMs for what they know about a business / brand / product / topic' and defines the output as a visibility score (0-100) per model. This clearly states what the tool does and distinguishes it from sibling tools like 'ask_pipeworx' or 'query' by focusing on AI-model knowledge scoring rather than general Q&A.

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 concrete use cases ('AI-marketing audits, pre-launch brand checks, competitive monitoring') and explains model selection defaults ('Default model is Workers AI Llama-3.3-70b (free)'). It does not explicitly name alternatives or exclusion criteria, but the context is clear enough for an agent to decide when to invoke it.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is well-covered. The description adds crucial behavioral context: that it routes to one of 5,563 tools, fills arguments automatically, returns pipeworx:// citation URIs, and works on every tier in one fast call. Lacks explicit warning about potential cost or rate limits, but the 'one fast call' implies efficiency.

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 comprehensive but verbose—about 150 words—with the most critical first sentence front-loaded. However, the usage guidelines paragraph is long and could be tightened. Several phrases like 'one fast call' and 'START HERE' are helpful but duplicate information. Every sentence earns its place, but it could be 20-30% shorter without losing value.

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

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

Given the tool's high complexity (routes to 5,563 tools, 14 domains, no output schema), the description fully covers purpose, usage, behavioral traits, and example queries. The rich schema (100% coverage, aliases documented) and annotations handle the low-level details, so the description only needs high-level context—which it provides thoroughly. No gaps for typical factual queries.

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

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

Schema description coverage is 100%, so the schema already documents that all 6 parameters are aliases for a single 'question' field. The description adds valuable real-world usage context (examples of what kinds of questions work) but doesn't add constraints or format details beyond what the schema provides. Baseline 3 is correct.

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

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

The description uses specific verbs like 'routes', 'fills arguments', and 'returns' with a clear resource ('authoritative structured data with citations'). It explicitly lists 14 data domains (SEC filings, FDA, FRED, etc.) and distinguishes itself from siblings by saying 'PREFER OVER WEB SEARCH' and naming ask_pipeworx_grounded and deep_research as alternatives for different use cases.

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

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

Provides explicit when-to-use: 'Use whenever the user asks "what is", "look up", "find", "get the latest"' and when-not-to-use: 'Step up only when needed: for a hallucination-resistant single answer...use ask_pipeworx_grounded; for a broad/multi-part question...use deep_research'. Also covers breaking-news edge case. This is gold-standard 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 adds significant context beyond annotations: it explains that candidate improvements may be active and how results are used for merging decisions. Annotations already indicate readOnly, idempotent, and non-destructive behavior, so the description's disclosure of the experimental nature and fallback behavior is valuable.

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 long and packs crucial information: beta identity, identical interface, experimental routing, current status, usage guidance, and behavioral guarantee. The first sentence immediately establishes purpose and scope. Minor redundancy in the last sentence could be tightened.

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 (5,563 tools, experimental routing), the description covers purpose, state, interface, usage, and outcome of experiments. It lacks return value details, but no output schema exists, and the stable sibling likely documents output shape. The description is thorough for a routing tool with strong annotations.

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

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

Schema coverage is 100% with descriptions for all parameters. The description adds meaning by stating the arguments are identical to ask_pipeworx, which implies all aliases work the same way. This reinforces the schema's clarity without duplication.

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 identifies this as a beta version of ask_pipeworx, a universal router to 5,563 tools, distinguishing it from the stable 'ask_pipeworx' sibling. It clearly states the purpose: to use experimental routing improvements when active.

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 clearly says to use this 'when you want the newest routing' and notes it currently matches the stable version. It doesn't explicitly say when not to use it or compare to all siblings like 'ask_pipeworx_grounded', but the context is strong.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description goes far beyond these by explaining the refusal mechanism (5 explicit reasons: not_in_source, no_tool_match, etc.), cost trade-off, and that it uses ONLY tool result data. No contradiction exists.

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

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

Highly efficient, front-loaded with the critical 'hallucination-resistant' purpose. Every sentence serves a purpose: behavior explanation, use cases, trade-offs, and refusal format. 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?

Despite having 6 parameters (all aliases), no output schema, and complex behavior, the description is remarkably complete. It explains the refusal model, return format, when to use alternatives, and the exact trade-off (cost vs. reliability). Completely adequate for an agent to select and invoke correctly.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds no parameter-specific guidance beyond what the schema provides (aliases for the question parameter). However, it does contextualize the single required parameter as a natural language question for high-stakes use.

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 'Hallucination-resistant answer mode for high-stakes reads' and details the process of extracting answers only from tool results. It clearly distinguishes from the sibling ask_pipeworx by specifying the grounded/non-grounding difference and when to prefer each.

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 guidance on when to use: high-stakes situations demanding verifiable citations (financial, legal, medical, public statements). Clearly states it costs an extra LLM call and to 'prefer ask_pipeworx for casual lookups,' offering a direct, actionable alternative.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds extensive behavioral context beyond this: low-confidence short-circuit status ('low_confidence_match'), closed-market status ('market_closed_or_inactive'), wide-spread illiquidity flag, and resolution-rule risk (cancellation_rule). It also discloses that resolved markets are usually de-indexed and route through the low_confidence_match path, which is crucial for an agent to interpret results correctly.

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 labeled sections (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, RESOLVER CONTRACT, etc.) and front-loaded with the primary purpose and usage examples. Every sentence adds unique detail, though the length could be slightly intimidating. It earns a 4 rather than 5 due to its density, but no section is redundant.

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 thoroughly: result.market fields, result.analysis with edge calculations and 24h-move warnings, result.evidence keying, resolver contract fields, parent_event extractor, and news fallback fields are all documented. Safety mechanisms and blocking statuses are also covered. This is a complete description for a complex tool.

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

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

Schema coverage is 100%, so baseline would be 3. However, the description adds substantial semantics beyond the schema: it explains what 'question text' means, provides examples for the market parameter, clarifies depth modes by giving source counts ('quick = 2-3 evidence sources'), and explains include_raw's purpose and size implications. This goes far beyond the schema descriptions.

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

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

The description begins with a specific verb+resource: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It clearly distinguishes this from siblings like polymarket_edges or validate_claim by emphasizing bet-specific research with fan-out to evidence sources. The input flexibility (slug, URL, question text) is also clearly stated.

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

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

Explicit usage guidance is provided: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It also gives concrete fan-out examples for different bet types and notes alternatives implicitly by listing classifiers and category-specific data packs. The description is exceptionally actionable about when to use this 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?

Even though annotations already declare readOnlyHint=true and openWorldHint=true, the description adds substantial behavioral context: it specifies data sources (SEC EDGAR/XBRL for companies, FAERS for drugs), explains how off-calendar fiscal years are handled, notes that results are sorted by primary metric, and mentions the return format (paired data + pipeworx:// citation URIs). This goes far beyond what annotations cover, giving the agent a clear model of the tool's internal 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 dense but front-loaded with trigger phrases and the core purpose. It uses dashes and clear sections to separate trigger examples, data source details, and output format. While slightly verbose, every sentence adds value and the structure aids comprehension. A 4 is warranted because it's somewhat long but not 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?

Considering there is no output schema, the description compensates by explicitly mentioning the return format (paired data + citation URIs), the data sources per type, fiscal year handling, and the benefit of replacing sequential lookups. It covers all essential aspects an agent needs to know to select and invoke the tool correctly, making it highly complete without an output schema.

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

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

Schema coverage is 100%, but the description adds significant meaning by explaining what each type ('company' vs 'drug') pulls: company data includes 'LATEST 10-K revenue + net income + cash + long-term debt,' while drug data includes 'FAERS adverse-event counts, FDA approval counts, active trial counts.' It also clarifies that values are tickers/CIKs or drug names, and that results are ordered by primary metric, far exceeding the schema's basic enum and array definition.

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

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

The description clearly states a specific verb ('compare') and resource ('entities'), and explicitly defines the action as 'side-by-side comparison of 2–5 companies or drugs in ONE parallel call.' It distinguishes itself from sibling tools like entity_profile by emphasizing the parallel comparison aspect and listing concrete trigger phrases.

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

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

The description provides explicit usage guidance: 'ALWAYS PREFER over sequential single-pack lookups when comparing entities' and states 'Replaces 8–15 sequential lookups.' It also enumerates example queries ('Compare X and Y', 'rank these companies', 'head to head') that signal when to invoke this tool, making the decision boundaries clear.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, covering safety. The description adds value by specifying the exact output fields and the downstream use of resource_id, which goes beyond annotation information and helps the agent understand the tool's results.

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

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

The description is two concise sentences that front-load the action and scope, then list return fields and next steps. Every word earns its place, and there is no redundancy or filler.

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

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

For a simple search tool with rich annotations, full schema coverage, and no output schema, the description provides essential return fields and usage guidance. It tells the agent what the tool returns and how to proceed, making it complete and self-contained.

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

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

The input schema has 100% description coverage for all three parameters (query, limit, offset), so the baseline of 3 applies. The description does not add extra parameter-level detail beyond the schema, only mentioning 'by keyword' which aligns with the query parameter.

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 function: 'Search the Cook County Open Data catalog of open datasets by keyword.' It names a specific resource and verb, and lists return fields, distinguishing it from sibling tools like query/metadata. The addition of 'pass the resource_id to query/metadata' further clarifies its role in the workflow.

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

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

The description implies when to use the tool (when searching by keyword) and explicitly instructs the next step ('pass the resource_id to query/metadata'), offering clear usage context. However, it does not explicitly state when not to use it or name alternative search tools, leaving a slight gap.

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

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

Annotations (readOnlyHint, idempotentHint) already indicate safe read-only behavior. The description adds rich behavioral details: returns verbatim evidence with confidence/source/citation/gaps[], shows contradictions for standard/thorough, semantically excerpts large records, and provides latency expectations (15-90s). 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 quite long but every sentence adds essential information (prerequisites, comparisons, behavior, output format, depth details). It is front-loaded with the account requirement. While dense, it could be more structured with paragraphs or bullet points, but it remains informative without wasted words.

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

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

Given no output schema, the description thoroughly explains the return format: findings packet with verbatim evidence, confidence, source, timestamp, pipeworx:// citation, gaps[], contradictions[], hop field, and citation_uri condition. It also covers depth variations, latency, and limitations (empty gaps for non-structured topics). This fully equips an agent to understand and 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?

The input schema already provides comprehensive descriptions for both parameters (question and depth with enum explanation). The description enhances understanding by clarifying the 'second-hop iteration' logic for depth levels and the natural-language suitability for broad questions, but the schema already covers the core semantics, so the added value is moderate.

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

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

The description clearly states the tool's purpose: 'Grounded multi-source research across Pipeworx's 1462 STRUCTURED data sources' returning a findings packet. It explicitly distinguishes from siblings like ask_pipeworx, which is for single lookups or breaking news. The verb 'research' and resource 'structured data sources' are specific.

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

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

The description provides explicit when-to-use and when-not-to-use guidance: requires a free account (paid for thorough depth), contrasts with ask_pipeworx for single lookups and current news, and explains depth levels and their appropriate scenarios. It also suggests alternatives and mentions prerequisites.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the description need not restate safety. It adds valuable behavioral context: returns top-N tools, including names, descriptions, and full input schemas with curated examples, ready to call directly—information not present in annotations. This exceeds the baseline.

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

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

The description is front-loaded with a clear one-sentence summary. The long domain list is slightly repetitive but serves as useful discovery context. Every sentence contributes (usage, return value, and timing), and there is no filler. It is appropriately sized for a meta-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?

The tool is conceptually simple, and the description covers purpose, usage context, and return payload (top-N tools with schemas and examples). With no output schema, the description's explanation of return format is valuable. It omits edge-case behavior like empty results, but overall it is complete enough for an agent to select and invoke the tool correctly.

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

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

Schema description coverage is 100%, so the input schema fully documents all six parameters, including aliases and limits. The description mentions 'top-N' loosely but does not add parameter-specific meaning beyond the schema. Baseline of 3 is appropriate since the schema does the heavy lifting.

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

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

The description begins with 'Find tools by describing the data or task,' clearly identifying the verb (find) and resource (tools). It explicitly distinguishes itself from siblings by stating 'Call this FIRST when you have many tools available and want to see the option set,' and the extensive domain list (SEC, FDA, FRED, etc.) makes its scope 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 states 'Use when you need to browse, search, look up, or discover what tools exist' and instructs 'Call this FIRST' in many-tool scenarios. It also hints at when not to use it ('not just one answer'), though it does not explicitly name alternative tools or exclusions, so it narrowly misses a 5.

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 with strong annotations (readOnlyHint, idempotentHint, destructiveHint=false), the description adds meaningful behavioral detail: it fans out across multiple sources in parallel, soft-fails for patents due to API sunset, uses a fallback chain for news (GDELT→GNews), and returns fundamentals sorted by period_end. This goes well beyond what the annotations disclose.

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 trigger phrases, but it becomes a long run-on sentence after the colon, mixing examples, source list, output fields, and fallback behavior. It is appropriately sized for the tool's complexity, though better paragraphing would improve scannability.

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: it enumerates CIK, company_name, recent_filings, fundamentals, patents, news, and LEI, plus URIs and sorting details. It also covers input constraints and known failure modes (patents sunset, name resolution), making the tool's behavior sufficiently transparent for an agent to 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?

The input schema already covers both parameters with clear descriptions, but the description adds practical nuance: the value should be a ticker or zero-padded CIK (with example), and names are explicitly not supported. This reinforces and clarifies the schema rather than merely repeating 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 opens with concrete user phrasings and immediately states what the tool does: produce a full cross-source profile of a US public company in one parallel call. It specifies the exact output components (CIK, filings, fundamentals, patents, news, LEI), clearly distinguishing it from single-source or chained 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 explicitly says when to use this tool: whenever the user asks for a holistic view, and 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups.' It also provides an exclusion condition: names are not supported, and the agent should use resolve_entity first if only a name is available.

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 readOnlyHint=false. The description adds context about appropriate deletion scenarios but doesn't disclose additional behavioral traits such as irreversibility or whether deletion is permanent. It doesn't contradict annotations.

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

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

The description is two sentences, front-loaded with the action, and includes usage guidance without any fluff. 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?

For a simple one-parameter tool with good annotations, the description covers purpose and usage. It doesn't mention the response format or edge cases like deleting non-existent keys, but the tool's simplicity and annotations fill most gaps.

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

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

The schema covers the single 'key' parameter completely (100% coverage) with a clear description. The tool description only repeats 'by key' and doesn't add extra semantics like formatting or key constraints.

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

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

The description clearly states the tool deletes a previously stored memory by key, using a specific verb and resource. It distinguishes itself from sibling tools like 'remember' and 'recall' by explicitly focusing on deletion.

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

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

The description gives explicit use cases: when context is stale, task is done, or to clear sensitive data. It also mentions pairing with 'remember' and 'recall', but doesn't explicitly state when not to use this 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 readOnly/idempotent/destructive hints. The description adds process details (fetches the page, extracts title/description/key links, emits standard markdown) and output format (single text blob for site-root/llms.txt), which goes beyond the annotations and gives the agent a clear behavioral model.

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, front-loaded with the core purpose, and the use-case list adds practical value without unnecessary length. Every sentence contributes meaning, and the formatting is clean.

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?

Since there is no output schema, the description's explanation of the output ('single text blob ready to drop at site-root/llms.txt') is critical and well-provided. Combined with full parameter descriptions and strong annotations, the description is complete for agent use.

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

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

Schema descriptions cover both parameters (url and max_links) with clear explanations, including default and max for max_links. The description doesn't add additional parameter-level detail beyond mentioning 'any URL', so baseline 3 is appropriate for full 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 clearly states the tool generates a production-ready llms.txt file for any URL, using a specific verb (generate) and resource (llms.txt file). It distinguishes from siblings by focusing on file generation rather than visibility checks or scanning, and the use cases further clarify its purpose.

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

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

The 'Useful for' section explicitly lists three clear contexts: getting a client's site indexed, drafting llms.txt for a project, and auditing competitors. It doesn't name alternatives or exclusion criteria, but the contexts are specific enough to guide selection.

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, so the safety profile is well covered. The description adds useful behavioral context by noting it returns the caller's own subscriptions and includes specific fields. This goes beyond annotations but doesn't contradict them, earning a solid 4.

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

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

The description is two sentences, front-loaded with the action and return fields. Every word contributes to understanding. It is compact without being under-specified, just the right size.

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 simple with one optional parameter and no output schema. The description lists return fields and provides usage guidance, covering the essentials. It doesn't mention default behavior (only active) explicitly, but that's implied and described in the schema. Overall, it's sufficiently complete for this low-complexity tool.

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

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

Schema coverage is 100% for the only parameter (include_inactive), which has a clear description. The tool description does not add extra meaning to the parameter, but the schema fully documents it. Baseline 3 is appropriate since the description adds no param-specific insights beyond what the schema provides.

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

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

The description clearly states the tool lists the caller's active subscriptions, with a specific verb ('List') and resource ('subscriptions'). It distinguishes itself from sibling tools like subscribe and unsubscribe by focusing on listing. It also enumerates the exact fields returned, leaving no ambiguity about what the tool does.

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

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

The description provides a clear use case: 'review what you're monitoring before adding more or to find an id to cancel.' This explicitly tells users when to use the tool. It doesn't mention alternatives (e.g., subscribe/unsubscribe), but the context makes it obvious that this is for listing, not modifying subscriptions.

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, covering the safety profile. The description adds meaningful context beyond the annotations by specifying exactly what metadata fields are returned (columns, types, row count, category, last-updated). It does not contradict the annotations and provides useful information about the return value, which is sufficient for a simple read-only retrieval operation.

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

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

The description is a single sentence that front-loads the action ('Get') and the resource, immediately followed by the return fields and the input example. Every word earns its place, and there is no redundancy or filler. It is compact yet informative.

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

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

For a tool with one required parameter, rich annotations (read-only, idempotent), and no output schema, the description fully covers what the tool does and what it returns. It lists the key metadata fields and gives a concrete example of the input. There is no ambiguity about the tool's behavior, making it complete for its simple scope.

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

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

The schema already covers 100% of the single parameter, stating that resource_id is a 'Dataset id, e.g. "cjeq-bs86"'. The description repeats this example and adds that it's a Cook County Open Data resource, but does not add any new meaning beyond what the schema provides. With full schema coverage, the baseline is 3, and the description doesn't elevate it further.

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 is very specific: 'Get a Cook County Open Data dataset's schema + metadata (columns, types, row count, category, last-updated) by resource_id'. The verb 'Get' clearly indicates retrieval, and the resource is precisely scoped to the dataset metadata for a given resource_id. It also distinguishes itself from sibling tools like 'datasets' and 'query' by focusing on schema and metadata rather than listing datasets or running data queries.

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 by defining the input (resource_id) and the output (columns, types, row count, etc.), implying it should be used when one needs dataset structural information. However, it does not explicitly state when not to use it or mention alternatives, such as using 'query' for actual data retrieval or 'datasets' for finding available datasets. This is a minor gap but the use case is clear enough for a single-parameter metadata lookup 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?

The description adds significant behavioral context beyond the annotations, including rate limits ('Rate-limited to 5 per identifier per day'), cost ('Free; doesn't count against your tool-call quota'), the claim_token workflow for tracking and reading resolution status, processing cadence ('team reads digests daily'), and guidance on not pasting user prompts. These details are not present in annotations.

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

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

The description is long but every sentence contributes useful information (purpose, use cases, exclusions, workflow, constraints). It is front-loaded with the core purpose and follows a logical sequence. It could be broken into bullets for readability, but it contains no fluff or redundancy.

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

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

Given the tool's moderate complexity (4 params, nested context, no output schema), the description covers all key aspects: when to use, what to include, claim_token lifecycle, and constraints. It doesn't fully describe the immediate response structure beyond mentioning claim_token, but it provides enough context for an agent to understand and use the tool effectively.

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

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

Since schema description coverage is 100%, baseline is 3. The description enhances parameter understanding by explaining how claim_token works ('Filing without an account returns a claim_token; pass it back later... to read whether it was fixed and what changed') and by advising on message content ('Describe the issue in terms of Pipeworx tools/packs — don't paste the end-user's prompt'). This adds value beyond the schema's per-parameter descriptions.

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

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

The description clearly states the tool's purpose: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It uses a specific verb (tell/send), resource (Pipeworx team), and distinguishes itself from sibling tools by focusing on feedback types (bug, feature, data_gap, praise) rather than queries or research.

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

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

The description explicitly says when to use the tool ('Use when a tool returns wrong/stale data...', 'when a tool you wish existed isn't in the catalog', 'when something worked surprisingly well') and provides an exclusion: 'if the tool came from a different MCP server... file it with that server instead.' It also clarifies how to identify Pipeworx tools, making usage unambiguous.

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 valuable behavioral context: it explains the data source (CF analytics-engine), confirms no PII, specifies the returned tuple structure (pack, tool, count), and mentions caching behavior (5min-1h depending on window). This goes well beyond the annotations and gives the agent a complete picture of what to expect.

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

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

The description is well-structured and front-loaded: it opens with a concise statement of what it returns, then lists concrete use cases, and ends with technical details on data provenance and caching. No sentence is wasted; the length is justified by the useful information it conveys.

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 adequately explains the return values (top tools, top packs, total call volume) and even gives the data shape (pack, tool, count). It also covers caching, privacy, and parameter behavior, making the tool fully understandable for selection and invocation. The inclusion of use cases adds contextual richness.

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

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

The input schema covers the single 'window' parameter with a full description including defaults and tradeoffs ('24h (default) | 7d | 30d. Shorter windows surface what's hot right now; longer windows show steady-state demand.'). The tool description repeats this information without adding new semantics, so with 100% schema coverage, the baseline score of 3 is appropriate.

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

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

The description clearly states what the tool does: returns trending data on what other AI agents are calling on Pipeworx, specifically top tools, top packs, and total call volume over a window. It uses a specific verb ('returns') and resource ('trending agent usage'), and distinguishes itself from sibling tools by focusing on self-aggregating signal from CF analytics-engine.

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

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

The description explicitly lists three use cases under 'Useful for,' which tell the agent when to use this tool (discovering hot data sources, confirming canonical choices, checking alignment with agent demand). It does not explicitly mention alternatives or when not to use it, but the provided contexts are clear enough for a simple read-only tool.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description adds no contradiction. It substantially expands on behavior: explains the Jaccard similarity threshold for cross-event pairing, the placeholder filter with 20% fraction rule, the fill check against live CLOB depth, and when a trade should be avoided ('do not trade it'). All of this is valuable context beyond the schema and annotations.

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

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

The description is long but every sentence earns its place. It is structured with clear labels (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) and front-loaded with the core purpose. No filler or redundant phrasing; it is dense with actionable detail.

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 fills the gap by specifying the response structure: opportunities[] with gap_pp, suggested_trade, reasoning, and monotonicity context, plus the partition_check fields and fill_check output. It also covers edge cases like skipped_low_similarity and placeholder filtering, making it complete for an AI agent to invoke correctly.

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

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

The schema already describes both parameters with 100% coverage, but the description adds deep semantic meaning: it explains the difference between event and topic modes, gives example slugs and seed questions, notes that full URLs are accepted, and describes the different checks each mode runs. This goes well beyond the schema's basic property 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 opens with a precise verb and resource: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It clearly distinguishes this from sibling tools like polymarket_edges and polymarket_fill_risk, and explains the three invocation modes (no args, event, topic).

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 guidance: 'Call with NO args for a trending_scan... pass event for the strongest per-event partition_check, or topic for a themed cross-event scan.' It also names an alternative for custom sizing ('For custom sizing use polymarket_fill_risk') and provides concrete examples for each mode.

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 readOnly/idempotent annotations, the description discloses critical behaviors: caching ('Cached 1h at the KV level keyed on all knobs'), model-specific details (e.g., 'soft signal w/ halved Kelly', 'rare-by-design'), and diagnostic output ('_diagnostics... so callers can see WHY a segment is empty'). It also explains that Fed bets are excluded from ranking due to unreliable signals, adding transparency not conveyed by annotations.

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

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

Despite its length, the description is densely informative and well-structured with clear section markers like 'FIVE MODEL FAMILIES', 'TRADEABLE-EDGE KNOBS', and 'RESPONSE TOP-LEVEL'. Every sentence contributes unique value—covering purpose, model details, output format, knob behavior, and caching—without redundancy, making it efficient for its complexity.

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

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

With no output schema, the description fully explains the response structure: by_segment segments, fed_candidates/fed_note, and _diagnostics with funnel counters. It also covers edge calculation (edge_pp_net after slippage), risk metrics (kelly_fraction_half capped at 0.25), and filtering rationale (why segments can be empty), making the tool's behavior understandable even without an output schema.

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

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

Although the schema covers all 9 params, the description adds substantial meaning beyond the raw property names. For example, it explains that min_kelly 'Skips opportunities that are too small to bet sensibly even if the edge is large', that min_partition_leg_kelly applies per-leg because 'Partition arbs always return kelly_fraction_half=0 at the parent level by design', and provides concrete defaults and their impact (e.g., 'Set to 5000 to drop thin-book opportunities'). This enriches the schema with domain context.

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 first sentence clearly states the verb and resource: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It also distinguishes itself from siblings by specifying the intended use case ('what should I bet on today') and by covering multiple model families across three segments, unlike focused sibling tools like polymarket_arbitrage or polymarket_fill_risk.

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 states the primary use case ('agents discover opportunities without paging hundreds of markets') and provides extensive guidance on how to configure knobs for different scenarios (e.g., 'Bump for very thin partitions; drop to 0 if you have a smarter fill model'). However, it does not explicitly exclude alternative tools or mention when not to use this tool, so it lacks explicit exclusions.

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

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

Annotations already indicate a safe read-only, idempotent operation, but the description adds critical behavioral context: 60-day snapshot TTL, cache-miss-based snapshot creation, daily-closing basis for decay numbers, and interpretation of gaps. 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?

Though long, the description is well-structured with Args, RESPONSE, and LIMITS sections, and every sentence provides essential detail. Purpose is front-loaded, making it easy to parse despite the density.

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

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

Given the absence of an output schema, the description thoroughly explains the return format (tracked, expired, snapshot_dates) with field-level meanings, caveats, and data provenance. It also covers limitations like TTL and gaps, making it complete for reliable invocation.

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

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

Schema covers both parameters fully, so baseline is 3. The description adds meaningful nuance by defining 'lookback', 'snapshot family', and default/max values, plus clarifying the available window options. It enriches the schema without redundancy.

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

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

Clearly states it provides edge persistence and decay telemetry, answering 'how long has this edge existed and is it shrinking?' Distinguishes from sibling polymarket_edges by focusing on historical tracking rather than current edge values.

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

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

Provides clear context for use (evaluating edge age and trajectory) and hints at when it applies via the distinction between fresh and old edges. However, it does not explicitly name alternatives or state when not to use it, leaving the comparative guidance implied rather than explicit.

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, but the description adds substantial behavioral context: it walks the order-book ladder, returns specific metrics, handles two modes, applies defaults and clamps, and warns about partial fills creating unhedged directional risk. This goes well 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 long but every sentence earns its place. It uses CAPS labels (SINGLE-MARKET, BASKET) and structured lists to efficiently convey two modes, return fields, and usage rationale. The front-loaded sentence immediately states the tool's purpose, and the text remains organized despite its density.

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

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

Given the tool's complexity (two modes, 4 parameters, no output schema), the description is remarkably complete. It enumerates all return fields for both modes, explains edge cases (thin_legs, forced_directional_risk), provides size_usd interpretation, and gives clear usage context relative to sibling tools. The absence of an output schema is compensated by the exhaustive field listing.

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?

Although schema coverage is 100%, the description adds meaningful semantics beyond the schema: it explains the dual interpretation of size_usd (spend on buys, target proceeds on sells, settlement notional in basket mode), clarifies the default and clamp range, and distinguishes market vs event modes. The side parameter meanings are amplified with mode-specific details.

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

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

The description clearly states a specific verb+resource: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It distinguishes itself from sibling tools by explicitly positioning as the risk check to run before acting on polymarket_arbitrage or polymarket_edges signals.

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

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

Provides explicit when-to-use guidance: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains why (theoretical overround on thin books is not capturable) and clearly differentiates single-market and basket modes with conditional instructions.

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 readOnlyHint and idempotentHint annotations, the description richly discloses failure modes and interpretability hazards. It explains exactly when compatibility_warning fires (two distinct cases), how temporal_alignment can invalidate spreads, and what the skipped_cross_type/subtype counters reveal. It also states that the spread is meaningless when bet shapes are non-equivalent, giving the agent critical context to judge the reliability of results.

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

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

The description is long but exceptionally dense. It is front-loaded with the core concept, then organized by labeled sections (TWO MODES, RESPONSE, SAFETY FIELDS). Every sentence contributes either operational guidance or risk disclosure. The use of concrete examples and concise parentheticals maintains readability despite the length.

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

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

Given no output schema, the description thoroughly covers the response shape: leg-by-leg prices, matched spread[] with top_spreads_pp, compatibility_warning conditions, temporal_alignment, and skipped counters. It also explains how to interpret the absence of matches and why that matters. This is a complete operational picture for an agent to invoke and interpret the tool successfully.

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 documents all three parameters with 100% coverage. The description adds value by explaining the relationship between parameters: explicit tickers/slugs override the topic-mapped side, and the two explicit identifiers are meant to be used together for custom pairings. It also elaborates on the topic enumeration (repeating it) and clarifies that topic shortcuts may not yield comparable events.

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

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

The description opens with a precise verb+resource: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It further defines the metric (Kalshi − Polymarket in percentage points) and clearly distinguishes itself from sibling tools by focusing on cross-venue spreads. The two operating modes (topic shortcuts vs explicit event identifiers) are 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 explains when to use each mode: 'topic' for 10 pre-mapped macro shortcuts, and explicit tickers/slugs for custom pairings. It also provides important negative guidance by warning that 'most pre-mapped topics return compatibility_warning today' and that 'pre-mapped ≠ tradeable.' However, it does not explicitly contrast with sibling tools like polymarket_arbitrage, so the guidance stops short of full alternative selection.

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, and destructiveHint=false. The description adds the behavioral nuance that SoQL clauses should be passed 'without the leading $', and it states the return format ('Returns matching rows as JSON'). This goes beyond the annotations and schema descriptions, providing useful execution context.

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

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

The description is two sentences, front-loaded with the primary action, and every phrase adds value. It efficiently covers the querying mechanism, clause syntax, and return format with no wasted words.

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

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

For a query tool with 7 parameters and no output schema, the description is reasonably complete. It covers the input (resource_id), the query options (SoQL clauses, limit/offset), and the output (JSON). It does not mention default limits or error handling, but the schema covers default limit, and the description provides enough for an agent to proceed.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning by grouping parameters (where/select/group/order) and clarifying the no-$ syntax, which is not explicit in the individual schema descriptions. It also emphasizes resource_id as the key parameter, reinforcing the schema's required field.

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 function: 'Run a Socrata SoQL query against a Cook County Open Data dataset by resource_id'. It specifies the action (run), the resource (dataset), and the query language (SoQL), with an example resource_id. This distinguishes it from sibling tools like 'datasets' (which likely list datasets) by focusing on querying rows.

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

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

The description implies usage context: use this when you need to query rows from a specific dataset using SoQL filters. It mentions the key operation, but does not explicitly state alternatives or exclusions (e.g., 'use datasets to find resource_id'). Still, the context is clear enough that an agent can infer when to select this 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 establish read-only, idempotent, and non-destructive behavior. The description adds useful context beyond those: it can list all saved keys when key is omitted, and it is scoped to the caller's identifier, which has privacy implications. No contradictions with annotations exist, and the added detail is valuable.

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, with the primary action stated up front. Each sentence earns its place: one explains retrieval and listing, one gives use cases, and one describes scoping and complementary tools. No redundant or filler content.

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

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

For a single optional parameter with no output schema, the description covers the tool's purpose, usage context, scoping, and relation to sibling tools. It fully answers what the tool does, when to use it, and how it fits into the memory lifecycle, making it complete for the tool's simplicity.

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 documents the key parameter and its omit-to-list-all behavior, so description coverage is 100%. The description reinforces this by tying the key to values saved via remember, but it does not add significant new meaning beyond what the schema provides. Baseline 3 is appropriate for high 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 opens with a specific verb and resource ('Retrieve a value previously saved via remember'), and also clearly distinguishes the list-all-keys behavior when the key argument is omitted. It is easily differentiated from sibling tools like remember and forget, which are explicitly named for the save/delete counterparts.

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 clearly states when to use this tool: to look up context the agent stored earlier, avoiding re-derivation. It also provides scoping context (anonymous IP, BYO key hash, or account ID) and points to complementary tools (remember to save, forget to delete). However, it does not explicitly name alternatives to avoid or state when not to use it, stopping short of a 5.

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, destructiveHint), the description discloses a state-changing behavior: setting mark_read:true flags events as read and affects future calls. It also describes the return payload fields (source, citation_uri, raw event) and notes the feed is persisted. This adds significant context without contradicting annotations.

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

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

The description is compact and front-loaded: four sentences cover purpose, return format, filtering, mutability, and an alternative access method. Every sentence adds new information without repetition or padding.

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 effectively explains what the tool returns (source, citation_uri, payload), how parameters affect results, and the mark_read side effect. It also anticipates polling use cases and provides an alternative for non-agent scripts. This fully covers the tool's behavior in context.

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 all 5 parameters with 100% coverage. The description adds value by giving an example for type ('sec_8k'), specifying ISO format for since, and explaining the side-effect of mark_read. It does not explain limit or unread_only, but those are self-explanatory in the schema.

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

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

The description clearly states the tool 'Pull fired events from your subscription feed' with a specific verb and resource. It further explains it returns the most recent alerts written by the evaluator, distinguishing it from siblings like recent_changes or list_subscriptions.

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

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

The description explicitly mentions 'Polls work fine' to indicate suitability for repeated polling, and provides an alternative access path (GET registry.pipeworx.io/alerts.json) for scripts and dashboards. It also shows how to filter by type and since, giving clear usage context.

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

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

Beyond the annotations (readOnly, openWorld, idempotent), the description discloses detailed runtime behavior: it fans out to multiple sources in parallel, uses a specific fallback chain, handles a known API sunset, and returns structured grouped changes with citations. No contradiction with annotations; it adds substantial 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?

The description is dense but efficiently organized: user-intent phrases, core capability, source breakdown, parameter examples, return shape, and alternative tool. Every sentence earns its place without repetition. It front-loads the most important information and uses compact punctuation to keep related details together.

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 multi-source complexity and lack of an output schema, the description covers the essential context: what sources are queried, how failures are handled, how `since` formats work, what the return structure includes (changes[], total_changes, citation URIs), and when to prefer a sibling. This is complete for an agent to select and invoke the tool correctly.

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

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

The schema already documents all three parameters (100% coverage), so the baseline is 3. The description adds value by giving concrete format examples for `since` (ISO vs relative shorthand), a recommendation ('Use "30d" or "1m" for typical monitoring'), and clarifying acceptable `value` forms (ticker or zero-padded CIK). This surpasses baseline.

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

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

The description opens with concrete user intents ('What's new with X' / 'latest on Y') and then defines the tool as a 'change feed for a company in the last N days/weeks/months in ONE parallel call.' It clearly names the resources involved (SEC EDGAR, GDELT/GNews, USPTO) and distinguishes itself from the sibling tool entity_profile, making the purpose unambiguous.

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

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

It provides explicit when-to-use guidance through natural-language query examples and directly names an alternative: 'Use entity_profile instead when you want the static profile... regardless of window.' It also explains fallback behavior (GDELT→GNews on rate limits/5xx) and notes the USPTO soft-fail, giving agents clear decision criteria.

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 valuable context beyond the annotations: memory is scoped by identifier, authenticated users get persistent memory, and anonymous sessions retain data for 24 hours. It also implies overwriting behavior via idempotentHint. No contradiction with annotations exists, and the added retention details are useful.

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 composed of five concise, purposeful sentences. It front-loads the core purpose, then provides usage scenarios, storage details, retention behavior, and pairing with related tools. No sentences are wasted, and the structure is easy to scan.

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

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

For a simple two-parameter tool, the description is complete: it covers purpose, when to use, storage scope, retention, and related operations. No output schema is needed, and the description fully compensates for the lack of additional structured context. The behavior is fully specified for an agent.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds examples of key names (e.g., "subject_property", "target_ticker") and says value is "any text," but these largely mirror the schema's parameter descriptions. It does not introduce meaning beyond what the schema already provides, so a 3 is appropriate.

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

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

The description clearly states the tool's function: "Save data the agent will need to reuse later." It uses a specific verb (save) and resource (key-value pair data), and distinguishes it from sibling tools by naming recall and forget for retrieval and deletion. Examples like "resolved ticker" and "user preference" further clarify the intended use.

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

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

Explicit usage guidance is provided: "Use when you discover something worth carrying forward." The description also explains when to use alternatives (recall to retrieve, forget to delete) and clarifies persistence differences between authenticated and anonymous sessions. This fully addresses when and how to use the tool versus its siblings.

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

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

Annotations already provide readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds transparency by explaining cascading lookups, graceful degradation of LEI/FIGI enrichment, and that unresolved identifiers are explicitly stated in the output. This adds useful behavioral context beyond the annotations.

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

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

The description is front-loaded with the purpose and examples, making it easy to scan. While it is lengthy, every sentence adds value, and the structure is clear with sections for supported types. It could be slightly more concise, but the information density is high.

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 (two entity types, multiple identifier sources, graceful degradation, cascading lookups), the description is remarkably complete. It covers input formats, output behavior (unresolved list), edge cases (ISIN resolution, non-US issuers), and reliability. Without an output schema, the description effectively explains the return values.

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

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

Schema coverage is 100% for both parameters, but the description enriches the meaning significantly. For 'type', it explains the two enum values with detailed return behavior. For 'value', it provides concrete examples (ticker, CIK, name for company; brand/generic for drug) and clarifies that ISINs are accepted. This goes beyond the schema's brief descriptions.

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

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

The description clearly states the tool resolves a user-spoken name to canonical/official identifiers that other tools require. It provides specific query examples ('What's the ticker for…', 'find the CIK for…') and explicitly says 'Use FIRST whenever you have a name but need an ID.' This distinguishes it from sibling tools like 'compare_entities' or 'entity_profile', which serve different purposes.

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

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

The description gives clear context on when to use the tool ('Use FIRST whenever you have a name but need an ID') and details supported types (company, drug) with input formats. It also mentions that the tool replaces 2-3 manual lookups, implying efficiency. However, it does not explicitly state when not to use it or mention alternatives, leaving some room for ambiguity.

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

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

Annotations (readOnlyHint, idempotentHint, destructiveHint) already establish safety, and the description adds valuable behavioral context: it probes each entity with ai_visibility_check, ranks by score, and returns a structured ranked list. This explains the internal mechanism and output format, going beyond the annotations without contradicting 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 two sentences, front-loaded with the core function, followed by a use case and return format. Every sentence earns its place with no redundancy or filler.

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

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

With no output schema, the description adequately explains the return value ('ranked list with score, confidence, signal density per entity') and the operational approach. It does not detail model-specific behavior (e.g., requiring _apiKey for anthropic), but the schema covers those parameter details, so the description is sufficiently complete for its 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 coverage is 100%, with each parameter already described in detail (e.g., entities as 2-8 items, first treated as subject). The description mentions 'your brand + N competitors' and 'score, confidence, signal density per entity,' but does not add new parameter 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 states a specific action ('Compare AI visibility across multiple entities side-by-side') and resource (AI presence across entities). It distinguishes itself from sibling ai_visibility_check by emphasizing multi-entity comparison and ranking, and from generic compare_entities by focusing on AI recognition scores.

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 concrete use case ('competitive AI-marketing audits') and an example query, clearly indicating when to use the tool. It does not explicitly exclude alternatives or state when not to use it, but the multi-entity focus strongly differentiates it from single-entity probes.

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

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

Annotations already set readOnlyHint/idempotentHint; the description adds critical operational context: partial failures degrade gracefully, bundlephobia can take 5-30s on first measurement, and sources_failed lists timeouts. It also clarifies the composite nature and ecosystem scope without contradicting annotations.

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

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

The description is dense but every sentence adds value: purpose, use cases, return structure, ecosystem limitation, and failure behavior. It is appropriately front-loaded with the tool's core function.

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

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

Given the complexity (external API fan-out, partial failures, no output schema), the description covers what it does, when to use, what it returns (including specific fields and sources_failed), and limitations. No critical information appears 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?

Both params (package, version) are fully described in the schema (100% coverage). The description's only additional parameter nuance is that version defaults to latest when omitted, which is already in the schema description. No deeper parameter semantics are added.

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

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

The description clearly identifies the tool as a composite check for npm packages, specifying the verb 'scan' and the exact purpose ('should I add this npm package to my project'). It enumerates the sources fan-out (deps.dev, bundlephobia) and the return fields, distinguishing it from sibling tools.

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

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

The description explicitly states when to use it ('Use whenever an agent asks "is X safe / popular / small"...') and provides a clear exclusion: 'NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly.' This gives both when and when-not guidance.

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

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

Beyond the annotations (readOnlyHint, idempotentHint, etc.), the description discloses concrete behavioral details: embedding model (BGE-base-en), chunking strategy (500-char overlapping windows), and the 200K character cap with truncation flagging. It also describes the return format, adding value beyond structured metadata.

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 a distinct purpose: definition, use case, pairing with sibling, and technical specifics. Front-loaded with the clearest statement of function. No wasted words; highly efficient and structured.

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

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

Despite lacking an output schema, the description explains return values (passages with offsets and similarity scores), behavior on large inputs (truncation), and the intended workflow. This is complete for a search tool with rich annotations and a well-described parameter set.

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 description need not compensate. It does reinforce the meaning of 'text' (content to search, not a reference) and 'query' (natural language), but this mostly mirrors schema descriptions. The description adds no significant param-specific semantics beyond what the schema already provides.

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

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

The description opens with 'Semantic search INSIDE a fetched record,' which is a specific verb+resource combination that clearly distinguishes it from broader search tools. It explicitly states the input (text already pulled) and output (top-N passages with offsets and similarity scores), making the tool's 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 provides explicit when-to-use guidance: 'Use when the record is too big to cram into the prompt.' It also names a complementary sibling (ask_pipeworx_grounded) and explains how the tools work together, which clearly differentiates it from alternatives.

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

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

Annotations already indicate mutation (readOnlyHint false) and non-destructiveness, and the description adds substantial detail: account eligibility restrictions, always-on feed retrieval path, SMS verification and daily cap, webhook signing secret one-time return, and auto-disable after 10 failures. 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 dense but well-structured: purpose and return value first, then account requirements, supported types with inline examples, and delivery details. Long sentences carry high information density without fluff.

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

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

For a creation tool with nested params and no output schema, it explains return value, prerequisites, type-specific parameter shapes, and delivery channel behaviors. The absence of an output schema is compensated by stating the returned subscription id and one-time webhook secret.

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

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

The input schema already documents all parameters at ~100% coverage with detailed examples, so baseline is 3. The description adds meaningful context beyond schema, e.g., item code semantics ('5.02' = officer change), 'topic:fed' example, and delivery behavior, though it partially duplicates schema examples. Overall it enhances rather than merely repeats.

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

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

The description opens with a specific verb ('Create') and resource ('proactive monitoring subscription to a live-data event stream'), and notes the returned subscription id. This clearly distinguishes it from sibling tools like list_subscriptions and unsubscribe.

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

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

It provides clear context: this is for creating persistent subscriptions, requires an OAuth account, and describes supported types and delivery channels. It does not explicitly state when not to use it or compare directly to alternatives, but the sibling names and mention of recent_alerts imply the workflow.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds valuable behavioral context by explaining the return format (category-bucketed example questions with tool + argument shape), that it draws from a live catalog, and that calling with no arguments gives the full spread. This goes beyond the annotations without contradicting 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 a single paragraph that front-loads the tool's intent with trigger phrases, then explains the return type, the topic parameter, and the recommended usage. While somewhat dense, every sentence adds meaningful information and there is no filler. The length is justified given the need to convey the tool's value and usage in an onboarding context.

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 simple (one optional parameter) but lacks an output schema, so the description carries the burden of explaining what the tool returns. It does this thoroughly: the return is category-bucketed example questions with exact tool + argument shapes, drawn from the live catalog. It also explains the no-argument vs. topic behavior and when to use the tool. The description is fully complete for this tool's complexity.

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

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

The input schema already provides 100% coverage with a detailed description for the optional `topic` parameter, listing valid focus areas and indicating to omit for a general spread. The description adds examples like 'finance', 'pharma', 'betting' and explains that passing topic focuses the response, but this largely reflects the schema's existing information. The baseline of 3 is appropriate since the schema does the heavy lifting.

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

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

The description clearly states the tool's purpose as 'the onboarding entry point for an agent that just connected and wants to know what is worth asking.' It specifies the resource (Pipeworx) and the action (suggest questions), and distinguishes it from siblings by noting it returns tool + argument shapes for example questions. This is a specific verb+resource description.

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

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

The description explicitly says 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' This provides clear when-to-use guidance and points to related meta-tools, but it does not explicitly state when not to use it or name alternative tools. It effectively conveys the intended context without exclusions.

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

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

Annotations already indicate non-read-only and non-destructive, but the description goes further by explaining the ownership check, deactivation (not deletion), and that historical events remain accessible via recent_alerts. This fully discloses side effects and aligns with the idempotent and non-destructive hints.

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

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

Two sentences, front-loaded with the core action, then the essential behavioral details. No wasted words.

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

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

For a simple one-parameter cancellation tool, the description covers the purpose, ownership constraint, and side effects. It omits explicit return/error behavior, but with no output schema and simple semantics, this is a minor gap.

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

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

The input schema fully documents the single 'id' parameter with a description ('returned by subscribe'), so the baseline is 3. The tool description adds the ownership context but does not add new parameter-level details beyond the schema.

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

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

Clearly states the action ('Cancel a subscription by id'), specifies the resource, and distinguishes from sibling tools like subscribe and list_subscriptions. Ownership enforcement adds precision.

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?

Implies when to use (to cancel your own subscription) and enforces an ownership restriction, but does not explicitly name alternative tools or conditions for when not to use. The deactivation note clarifies the effect versus other operations.

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

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

Adds substantial behavioral context beyond the annotations: explains the verdict set, the critical distinction between could_not_verify (did not happen) and unsupported (no source exists), the routing between SEC EDGAR/XBRL and the grounded pipeline, and that it returns a citation and reasoning. This is consistent with readOnly/idempotent annotations and greatly enhances safe invocation.

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 every sentence earns its place: trigger phrases, scope, internal routing, output semantics, error warnings, and efficiency note are all essential. It is front-loaded with the most critical calling signal (could_not_verify warning) and remains well-organized without redundancy.

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

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

Given there is no output schema, the description must explain return values—and it does thoroughly: verdict enum, actual value with citation, reasoning, and the error object for could_not_verify. It also covers the two routing paths and the efficiency gain. For a 2-parameter tool, this is fully sufficient.

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

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

Both claim and tolerance_pct already have detailed schema descriptions (100% coverage), so the schema carries the parameter semantics. The description does not introduce meaning beyond those schema descriptions—it only references 'exact percent-delta math' but doesn't elaborate on parameter usage. 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 opens with concrete trigger phrases ('Is it true that…' / 'fact check'), then states the core action: 'natural-language claim verification against authoritative sources.' It also gives a clear resource scope (claims about any factual statement) and distinguishes its output (verdicts like confirmed/refuted) from sibling search/ask 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?

Provides an explicit when-to-use: 'Use whenever the agent needs to check whether something a user said is factually correct.' It further breaks down the two internal subpaths (company-financial vs. all other claims), giving clear context for invocation. It doesn't name explicit exclusion frontiers or alternatives, but the claim-verification intent is distinct enough.

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