Texas DMV

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

Annotations already indicate readOnly, openWorld, idempotent, and non-destructive. Description adds valuable behavioral context: it discloses that the default model is free (Workers AI) and that Anthropic probing requires a BYO key (with cost implications). Also outlines the return structure per model, enhancing transparency beyond annotations.

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

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

Description is concise (three sentences) with no wasted words. Front-loaded with action, then details, then use cases. Each sentence adds value, and the structure is easy to parse.

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

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

Despite lacking an output schema, the description explains the return format (per-model object with score, confidence, signals, raw_response plus combined view). Parameters are fully covered, and the moderate complexity (4 params, 1 required) is adequately addressed. Minor gap: no mention of error handling or rate limits, but not critical given 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%, but description adds meaning beyond the schema: it explains the default model and free usage, clarifies the API key's purpose, and provides examples for the 'context' parameter (e.g., 'Boston restaurant'). This helps the agent understand how to use parameters effectively.

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

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

Description clearly states the tool probes LLMs for knowledge about an entity and scores visibility on a 0-100 scale per model. It specifies the return format and use cases (AI-marketing audits, pre-launch brand checks, competitive monitoring), making the purpose unambiguous and distinct 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?

Provides clear context on when to use (brand audits, competitive monitoring) and details like default model and API key requirement for Anthropic. Lacks explicit when-not-to-use or direct comparison to siblings, but the guidance is sufficient for most scenarios.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds valuable context: the tool routes to 5,305 tools, fills arguments, and returns structured answers with stable citation URIs. It also notes it works on every tier and is fast. No contradictions with annotations.

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

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

The description is fairly long but efficiently organized: it starts with the core instruction, lists supported domains, then provides usage guidelines and examples. Every sentence serves a purpose, though minor trimming could improve conciseness without losing substance.

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 broad scope and lack of output schema, the description adequately covers its functionality, context of use, and relationship to siblings. It mentions return type (structured answer with citations) and provides examples. No major gaps.

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

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

Schema coverage is 100% with all six parameters documented, including aliases for the question parameter. The description does not add significant meaning beyond the schema, which already fully describes the parameter's purpose and aliases. Baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose: it routes factual questions to a vast set of verified sources and returns structured answers with citations. It explicitly contrasts with web search and other siblings like ask_pipeworx_grounded and deep_research, making the tool's role 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 detailed when-to-use and when-not-to-use guidance. It instructs to prefer this tool over web search for factual queries, lists explicit contexts (e.g., SEC filings, FDA data), and specifies when to step up to alternatives (grounded for hallucination-resistant answers, deep_research for broad questions). Includes concrete examples.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds behavioral context beyond these: it explains that candidate routing improvements are enabled live when under test, and that currently no candidate is active, so it matches ask_pipeworx exactly. It clarifies that it is a full working router with fallback to nothing, meaning it is self-sufficient. No contradictions with annotations.

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

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

The description is concise, using three well-structured sentences. It front-loads the purpose ('Beta version of ask_pipeworx'), then explains the experimental nature and current state, and ends with usage instruction. Every sentence adds value, no wasted words.

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

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

Given the tool is a router with 5,305 tools and the annotations are thorough (readOnly, openWorld, idempotent, non-destructive), the description is complete. It explains the beta purpose, current equivalence to stable, and the fallback behavior. No output schema exists, but the response shape is stated to be identical to ask_pipeworx, and the description notes the same arguments and response shape.

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 clearly described in the schema as an alias for 'question.' The description does not add any additional meaning to the parameters beyond what the schema provides. Baseline score of 3 is appropriate given the rich 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 identifies the tool as the beta version of ask_pipeworx, explicitly stating it is an identical universal router with the same tools and arguments. It distinguishes itself from the stable ask_pipeworx by being the experimental edge where new routing improvements are tested.

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

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

The description provides explicit usage guidance: 'Use it exactly like ask_pipeworx when you want the newest routing.' It informs that currently it matches the stable router exactly, but implies it may have experimental routing when candidates are active. It does not explicitly state when not to use (e.g., if maximum stability is needed), but the context is clear.

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

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

The description adds significant behavioral details beyond annotations, such as the extra LLM call cost, the return structure (including refusal reasons), and the guarantee of using only tool results. There is no contradiction with annotations (readOnlyHint, idempotentHint).

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

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

The description is concise and well-structured, starting with the tool's core purpose, then explaining its mechanism, return format, use cases, and cost trade-off. Every sentence is meaningful and earns its place.

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

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

Given the tool's complexity (6 alias parameters, no output schema), the description is remarkably complete. It explains both success and refusal outcomes, the routing mechanism, and the tool's application boundaries, leaving little ambiguity.

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

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

The input schema already has 100% coverage with descriptions for all six parameters. The description does not add any further meaning beyond what the schema provides, so the baseline score of 3 is appropriate.

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

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

The description clearly states the tool's purpose as 'Hallucination-resistant answer mode for high-stakes reads,' and explains that it extracts answers solely from tool results. It distinguishes itself from the sibling 'ask_pipeworx' by emphasizing its use for factual, quotable scenarios.

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

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

The description explicitly specifies when to use this tool: 'whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts (financial verdicts, legal claims, medical lookups, public statements).' It also advises preferring 'ask_pipeworx' for casual lookups, providing clear alternatives.

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

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

The description discloses extensive behavioral traits beyond the annotations (readOnlyHint, openWorldHint, etc.). It details how the tool resolves markets, classifies bets, fans out to data packs, and handles various edge cases like low-confidence matches, closed markets, wide spreads, and resolution rule risks. This adds significant transparency.

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

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

The description is long but well-structured, starting with a summary and then breaking down into sections for classifiers, fan-out examples, response shapes, etc. While it could be slightly more concise, the length is justified given the tool's complexity and the information density.

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

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

Given the tool's complexity (3 parameters, no output schema), the description is remarkably complete. It covers inputs, behavior, response structure, safety checks, and edge cases. Without an output schema, the detailed description of the response shape compensates 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?

With 100% schema coverage, the description still adds value by providing examples (slug, URL, question text), explaining the depth parameter (quick vs thorough), and detailing when to use include_raw. This enhances understanding beyond the schema alone.

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

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

The description clearly states the tool researches a Polymarket bet by pulling Pipeworx data. It specifies the verb 'Research', the resource 'Polymarket bet', and the action 'pulling the relevant Pipeworx data'. This distinguishes it from sibling tools like polymarket_edges or polymarket_arbitrage which have narrower scopes.

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 for "should I bet on X", "what does the data say about Y", or "is there edge in Z"', providing clear usage scenarios. However, it does not explicitly state when not to use this tool versus alternatives, though the specificity of the use cases implies its appropriate 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 annotations (readOnly, idempotent), it discloses that company data comes from SEC EDGAR/XBRL with correct fiscal year handling, and drug data from FAERS/FDA. It also states results are sorted by primary metric, and returns citation URIs.

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

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

Description is front-loaded with key purpose and trigger examples, then follows with parameter details. Each sentence adds value, no wasted words.

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

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

Given the tool's complexity (two entity types, multiple data sources), the description fully explains what each type retrieves, how results are sorted, and why it replaces multiple lookups. No output schema needed; the summary of return format is sufficient.

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

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

Schema coverage is 100%, but description adds significant extra meaning: for each enum value it explains what data is pulled, and for values it specifies tickers/CIKs for company and drug names, with cardinality 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 it performs side-by-side comparison of 2-5 companies or drugs in one parallel call. It provides concrete trigger phrases like 'Compare X and Y' and 'which is bigger', and distinguishes itself from sequential lookups.

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

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

Explicitly says 'ALWAYS PREFER over sequential single-pack lookups' and gives clear guidance on when to use company vs drug type. The trigger examples help the agent decide when to invoke 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 indicate readOnly, openWorld, idempotent, non-destructive. Description adds account requirement, expected latency (15-60s, thorough up to ~90s), depth behavior (gap recovery, contradictions), and output fields (findings packet with evidence, confidence, source, citation, gaps[], contradictions[], hop field). 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?

Long but well-structured: account info first, then purpose, comparison, depth details, output format, performance. Every sentence adds value, no obvious redundancy. Could be slightly tighter but effective.

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

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

Given no output schema, description covers return format (findings packet with specific fields), limitations (empty gaps for non-catalog topics), auth requirements, and performance expectations. Completely addresses agent's needs for a complex tool.

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

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

Schema coverage is 100%, so baseline is 3. Description adds significant meaning: depth enum explained with number of facets and secondary behaviors (gap recovery, contradictions scan), question parameter described as natural language, broad/multi-part fine. Exceeds baseline.

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

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

The description clearly states the tool does grounded multi-source research across Pipeworx's 1391 structured data sources in one call, distinguishing it from siblings like ask_pipeworx (single lookup) and specifying when to use each. The verb 'research' and resource 'structured data sources' are precise.

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

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

Explicit guidance: use for broad/multi-part questions over structured data, avoid for breaking/current news (prefer ask_pipeworx). Also mentions account requirement and alternative ask_pipeworx if not signed in. Provides clear when-to-use and when-not-to-use.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds value by explaining that results include full schemas with curated examples and are ready to call without a second lookup. 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 front-loaded with the core purpose and usage guidance. It lists many example domains, which is slightly lengthy but still useful for context. Overall, it is well-structured and each sentence contributes value.

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

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

Despite lacking an output schema, the description explains that the tool returns top-N relevant tools with names, descriptions, and full input schemas with examples. This sufficiently informs the agent about the return format. Given the complexity (30 siblings), the description adequately covers what the tool does and when to use it.

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

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

Schema coverage is 100%, so baseline is 3. The description mentions that 'query' accepts natural language and that limit controls 'top-N,' which adds slight context beyond the schema. However, it does not provide detailed semantics beyond what the schema already describes.

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

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

The description clearly states 'Find tools by describing the data or task,' specifying the exact resource (tools) and action (discover). It lists numerous example domains (SEC filings, financials, etc.), making the purpose unmistakable. No sibling tool performs tool discovery, so it is well-distinguished.

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

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

Explicitly says 'Use when you need to browse, search, look up, or discover what tools exist for' and 'Call this FIRST when you have many tools available.' This provides strong positive guidance on when to use it, though it does not explicitly state when not to use it or name 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?

Beyond annotations (readOnly, idempotent), the description details the tool's behavior: it fans out across multiple sources (SEC, XBRL, USPTO, news, GLEIF), returns specific fields, notes that the USPTO patents API will sunset in May 2025 (soft-fail), and mentions fallback logic. This rich context informs the agent of side effects and reliability.

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

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

The description is well-structured with examples, purpose, usage preference, return details, and limitations. It is informative but slightly verbose; every sentence adds value, yet it could be more concise.

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

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

In the absence of an output schema, the description thoroughly explains all return fields (cik, company_name, recent_filings with URIs, fundamentals, patents, news, LEI) and covers limitations (patent sunset, name not supported). This makes the tool's behavior fully comprehensible for an agent.

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

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

Schema coverage is 100% with clear descriptions for both parameters. The description restates the parameter constraints (ticker/CIK, no names) but adds minimal new meaning beyond what the schema already provides. Thus, a 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 explicitly states the tool's purpose: 'full cross-source profile of a US public company in ONE parallel call.' It starts with concrete examples like 'Tell me about X' and clearly distinguishes from siblings by stating 'ALWAYS PREFER over chaining single-pack ... lookups' when a holistic view is needed.

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

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

The description provides explicit guidance: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups' for holistic views, and specifies that names are not supported, directing to 'use resolve_entity first if you only have a name.' This clearly indicates when and when not to use the 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 destructiveHint: true and idempotentHint: true. The description adds context about clearing 'sensitive data' but does not elaborate on behavior like idempotency or error handling for missing keys. It adds some value but not rich 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?

Three concise sentences: purpose, usage guidelines, and sibling tool mention. Every sentence adds value, and the key information is front-loaded.

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

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

For a simple single-parameter tool with annotations, the description covers purpose, usage context, and behavioral implications (clearing sensitive data). It lacks details on return values or error cases, but given the tool's simplicity, it is fairly complete.

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

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

Only one parameter 'key' with complete schema description ('Memory key to delete'). The tool description adds no additional semantic meaning beyond what the schema provides, so baseline 3 is appropriate.

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

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

The description clearly states the action: 'Delete a previously stored memory by key.' It uses a specific verb and resource, and distinguishes itself from sibling tools like 'remember' and 'recall' by implying a deletion action.

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

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

Explicitly provides when-to-use scenarios: 'when context is stale, the task is done, or you want to clear sensitive data.' It also mentions pairing with 'remember' and 'recall,' offering guidance on alternatives.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint; description adds process details (fetches page, extracts title/description/key links) and output format 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?

Four sentences, front-loaded with purpose, then details, then use cases. No wasted words.

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

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

For a two-parameter tool with full schema coverage and annotation safety profile, the description provides all necessary context including process, output, and use cases.

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

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

Schema has 100% coverage with descriptions for both parameters. Description adds minimal extra value beyond schema, primarily context on output format.

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

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

Description clearly states verb (generate), resource (llms.txt file from any URL), and distinguishes from sibling tools like scan_competitor_ai_presence by specifying the output format and 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?

Explicitly lists three use cases (client site indexing, own project drafting, competitor auditing) but does not mention when not to use or name alternative siblings directly.

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

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

Annotations already indicate readOnlyHint=true, destructiveHint=false, and idempotentHint=true. The description adds value by specifying the exact return fields (id, type, params, etc.), which is helpful beyond the safety profile.

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

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

Two sentences, no wasted words. The first sentence states the action and output, the second provides usage guidance. Ideal conciseness.

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

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

For a simple list tool with one optional parameter, the description covers purpose, return structure, and usage context. No output schema exists, but the description explicitly lists the returned fields, so completeness is high.

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% (one parameter with a description). The description does not add meaning beyond the schema: it mentions 'active' as default, which aligns with the parameter description, but no extra parameter context is provided.

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

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

The description clearly states it lists the caller's active subscriptions and enumerates the returned fields (id, type, params, etc.), distinguishing it from sibling tools like subscribe or unsubscribe.

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

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

Explicitly tells the agent when to use the tool: 'to review what you're monitoring before adding more or to find an id to cancel', providing clear use cases and avoiding alternatives.

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

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

Description discloses behavioral traits: rate-limited to 5 per identifier per day, free, doesn't count against quota. Annotations (readOnlyHint=false, etc.) are consistent; no contradiction.

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

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

Description is concise but fully informative. First sentence captures core purpose, followed by clear usage instructions, and ends with key behavioral notes. Every sentence adds value.

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

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

Given the tool's simplicity and lack of output schema, the description is complete. It covers purpose, parameters, usage scenarios, limitations, and behavioral traits.

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%. Description adds meaning by explaining each enum value in context, providing examples for message, and describing the optional context object's purpose.

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: sending feedback about issues, missing features, or praise. It lists specific categories (bug, feature, data_gap, praise) and distinguishes itself from sibling tools which are query/info 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?

Explicit usage guidance: when to use (bug, feature/data_gap, praise) and what to avoid (don't paste end-user prompt). Provides context on how feedback is used (digests daily, affects roadmap) and mentions rate limits and quota exemption.

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

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

Annotations indicate read-only, idempotent, non-destructive. The description adds caching behavior (5min-1h depending on window), data origin (CF analytics-engine), and privacy assurance (no PII), going beyond annotations.

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

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

The description is well-structured with use case bullets and concise sentences. Slightly verbose but information-dense and front-loaded with purpose.

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

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

For a simple tool with one param and no output schema, the description covers purpose, use cases, parameter semantics, caching, and privacy, leaving no critical 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 description explains the enum values in terms of trade-offs (short window for hot trends, long window for steady-state), providing meaning beyond the schema's enum list. Schema coverage is 100%, and the description adds value.

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

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

The description clearly states that the tool returns top tools, top packs, and call volume over a specified window, using the verb 'returns' and specific resource. It distinguishes itself from sibling tools by focusing on trending aggregation.

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?

Three explicit use cases are provided (discovering hot data sources, confirming canonical tool choice, aligning use case). While it does not list when not to use, the guidance is clear and context-rich.

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

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

The description discloses key behavioral traits beyond annotations: threshold for similarity (Jaccard >= 0.30), partition filter for placeholders, fill check against live CLOB depth, and when signals should be ignored. Annotations already mark the tool as read-only and non-destructive, and the description reinforces this with details about the analysis process.

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

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

The description is thorough but verbose, containing many detailed technical explanations that could be streamlined. It is front-loaded with the main purpose and modes, but the dense paragraph structure reduces readability. Every sentence adds value, but the overall length impacts conciseness.

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

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

Given the complexity of the tool (multiple modes, arbitrage detection, fill check, thresholds), the description is highly complete. It explains edge cases, response structure, and provides enough context for an agent to use the tool correctly without needing external documentation.

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

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

Schema coverage is 100% (both parameters documented), so baseline is 3. The description adds significant meaning by explaining the two modes, accepted input formats (slug or URL for event, seed question for topic), and the behavioral differences between them.

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: finding arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes from sibling tools like polymarket_edges and polymarket_fill_risk by specifying the core mechanisms and mentioning fill risk separately.

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

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

The description provides explicit guidance on when to use each mode: no args for trending scan, 'event' for specific event, 'topic' for cross-event scan. It also explains when not to trade (realizable_edge_pp <= 0) and references an alternative tool for custom sizing (polymarket_fill_risk).

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

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

The description goes far beyond the annotations (readOnlyHint, openWorldHint, etc.), revealing caching behavior ('Cached 1h at the KV level'), detailed response structure with diagnostics, and the 24h-move warning. It explains how edge is computed net of slippage and the Kelly sizing caps, providing transparency about potential pitfalls.

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

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

The description is well-structured with clear sections for model families, tradeable-edge knobs, and response format. It is front-loaded with the core purpose. However, it is somewhat verbose—some details about model formulas could be moved to the output schema or a separate doc without losing essential guidance.

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

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

Despite having no output schema, the description comprehensively explains the response structure (by_segment, _diagnostics, per-opportunity fields). It covers all relevant behavioral aspects, caching, and edge cases (e.g., empty segments explained via diagnostics). The tool's complexity is fully addressed.

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

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

Although the input schema already has 100% description coverage, the tool description adds significant meaning to parameters. For example, it explains why min_kelly doesn't filter partition arbs and how min_partition_leg_kelly compensates. It also elaborates on the purpose of slippage_pp, min_edge_pp, and tradeable-edge knobs, helping agents set them correctly.

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: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It distinguishes from siblings by focusing on Pipeworx edge detection and structured segments, and explicitly frames it for 'what should I bet on today.'

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 strong usage guidance, explaining when to use each segment (MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, CONCENTRATED_LONGSHOT) and how to use tradeable-edge knobs. It notes that Fed bets are excluded from ranking, adding clarity. However, it lacks explicit comparisons to sibling tools like polymarket_arbitrage or polymarket_edge_tracker, which could help agents decide between them.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds context about snapshot gaps, TTL (60-day), and that decay is computed on daily closes not intraday, enhancing transparency beyond annotations.

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

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

The description is detailed but well-structured, starting with a clear intro, then a question format, followed by bullet-like explanation of response fields. It is front-loaded with the core question and includes necessary details without excessive wordiness.

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 and the tool's complexity (time-series decay analysis), the description fully explains the output structure (tracked[], expired[], snapshot_dates[]) and behavioral nuances (gaps, decay computation). It is complete for an agent to understand tool usage and output.

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

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

Schema coverage is 100% with parameter descriptions. The description restates defaults and constraints (days: default 14, max 30; window: default '1wk'), adding marginal value. No enum or nested objects to further explain.

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: providing edge persistence and decay telemetry. It uses a specific verb 'answers' and resource 'edge persistence and decay telemetry', distinguishing it from sibling 'polymarket_edges' which generates the snapshots.

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

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

The description explains when to use the tool via the example comparing a fresh edge versus a 3-week-old edge, implying it's for assessing edge age and decay. It also describes the response structure and limits, but does not explicitly mention alternative tools or when not to use it.

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

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

Annotations declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. Description adds behavioral context like return fields (top_of_book, slippage, etc.) and risk warnings. No contradictions, but could mention any limits or side effects beyond annotations.

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

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

Description is detailed (~150 words) but well-organized with uppercase markers for modes. Every sentence adds value, though could be slightly more compact without losing clarity.

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

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

Covers both modes, return fields, defaults, and risk warnings despite no output schema. Lacks explicit statement of no mutations, but annotations cover that. Comprehensive for the complexity.

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

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

Schema coverage is 100%, and description enriches each parameter with mode-specific interpretations (e.g., side defaults, size_usd meaning for buys vs sells, market vs event requirement).

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

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

Description clearly states tool checks realizable vs theoretical edge against live order book depth for both single-market and basket modes. It distinguishes from siblings like polymarket_arbitrage and polymarket_edges by specifying when to use this tool before acting on their 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?

Explicitly says 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500' and explains why (theoretical overround not capturable on thin books, partial fills create directional risk).

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 extensively discloses behavioral traits beyond annotations: it explains compatibility_warning triggers, temporal alignment checks, and skipped cross-type/subtype counters. This adds significant context to the readOnlyHint, openWorldHint, and idempotentHint annotations, with no contradictions.

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

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

The description is long but well-structured with clearly labeled sections (modes, response, safety fields, temporal alignment). It is front-loaded with the core purpose and uses bullet points. While verbose, every sentence provides necessary detail, justifying its length.

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

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

Given the tool's complexity (cross-venue comparison with multiple edge cases), the description is comprehensive. It covers modes, expected response fields, safety warnings, temporal alignment, and statistical notes. Even without an output schema, the description adequately describes 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%, so baseline is 3. The description adds value by listing the 10 pre-mapped topic shortcuts and explaining that explicit parameters override topic-mapped sides. It also provides example values, which aids understanding beyond the schema alone.

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

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

The description clearly defines the tool as a cross-venue spread calculator between Kalshi and Polymarket. It explains two modes (topic shortcuts and explicit tickers) and distinguishes itself from sibling tools like polymarket_arbitrage by focusing on cross-venue comparisons, not intra-venue arbitrage.

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

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

The description explains when to use the tool (comparing same outcome across venues) and provides explicit warnings that many pre-mapped topics yield compatibility warnings and are not tradeable. It does not explicitly name alternative tools or state when not to use it, but the context is clear enough.

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

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

Annotations already declare readOnlyHint and idempotentHint. Description adds behavioral context beyond annotations: scoping to user identifier and behavior when key is omitted. No contradictions.

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

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

Description is front-loaded with the core action and use case. Slightly verbose but every sentence adds value (scoping, pairing with siblings). 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 no output schema, the description explains purpose, usage, scoping, and relationships with siblings. For a simple read/list tool, this is complete enough for an agent to understand 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 covers the single parameter fully (100% coverage). The description echoes the schema's note about omitting key to list all. Baseline of 3 is appropriate; description adds no new parameter-level semantics.

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

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

The description clearly states the verb ('retrieve' or 'list') and resource ('value previously saved' or 'saved keys'), and distinguishes from sibling tools remember and forget by naming them explicitly.

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

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

Description explains when to use (look up stored context) and implies when not to (use remember to save, forget to delete). Could explicitly mention alternatives, but the sibling context provides that.

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

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

Description states mark_read:true flags events as read, implying a write side effect. This contradicts the annotation readOnlyHint=true, which marks the tool as read-only. Such inconsistency undermines trust and could mislead an AI agent.

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

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

Concise paragraph with clear front-loading of main purpose, followed by relevant details. No redundant sentences.

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

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

With no output schema, description adequately lists returned fields (source, citation_uri, payload) and covers key behaviors (filtering, mark_read). Lacks pagination details but sufficient for a list tool.

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

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

Schema covers 100% of parameters with descriptions. The description adds value by giving examples (e.g. 'sec_8k'), explaining mark_read behavior, and noting ISO timestamp format, enriching parameter understanding beyond schema.

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

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

Description clearly states the tool pulls fired events from subscription feed, specifying fields returned (source, citation_uri, payload). It distinguishes from sibling tools by focusing on recent alerts and subscription feed context.

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 guidance on polling, filtering options, and mentions an alternative access method (GET registry.pipeworx.io/alerts.json). Does not explicitly exclude usage scenarios but gives enough context for typical use.

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

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

Annotations indicate readOnly, openWorld, idempotent, non-destructive. The description adds valuable behavioral details: fans out to multiple sources, fallback behavior, soft-fail for USPTO, and date shorthand acceptance. No contradiction.

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

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

Description is detailed but front-loaded with examples. Every sentence contributes useful information. Slightly verbose but well-structured.

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

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

No output schema, but description describes return structure (changes[] grouped by source, total_changes, citation URIs). Covers multiple data sources, fallback, and date formats. Complete for the tool's complexity.

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

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

Schema covers all 3 parameters with descriptions and enum. Description reinforces 'since' shorthand and provides usage recommendation ('30d' or '1m'). Adds extra context beyond schema, earning a score above baseline.

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

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

The description clearly states it provides a change feed for a company in a time window, with example queries and explicit distinction from sibling tool entity_profile. The verb 'change feed' and listing of sources (SEC, GDELT, USPTO) make the purpose unambiguous.

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

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

The description gives explicit 'when to use' with example queries and 'when not to use' with a direct instruction to use entity_profile for static profiles. It also explains fallback logic between GDELT and GNews.

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

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

Discloses key behavioral traits beyond annotations: key-value pairing, scoping by identifier, persistence differences (authenticated vs anonymous). No contradiction with annotations (idempotentHint=true is consistent with overwriting).

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 concise: three sentences covering purpose, usage, and behavior. Front-loaded with the core action, no redundant 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 key-value tool with no output schema, the description provides complete context: purpose, when to use, scoping, retention, and sibling relationships. No gaps.

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

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

Schema covers both parameters with descriptions (key: example patterns, value: any text). Description does not add new parameter info, so baseline 3 is appropriate.

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

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

The description starts with a specific verb 'Save data' and resource 'the agent will need to reuse later', clearly stating the tool's purpose. It distinguishes itself from sibling tools like recall and forget by positioning remember as the store operation.

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

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

Explicitly states when to use: 'when you discover something worth carrying forward'. Mentions pairing with recall and forget, but does not explicitly state when not to use. Still, provides sufficient context for correct invocation.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds that each call cascades through several lookup endpoints internally, replacing 2-3 manual lookups, which is valuable behavioral context beyond annotations.

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

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

The description is well-structured with examples, bullet points for entity types, and a clear statement of primary use case. Every sentence adds value, and it is front-loaded with the core purpose.

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

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

Despite no output schema, the description fully explains the return values for both entity types (ticker, CIK, RxCUI, etc.) and provides citation URIs. It covers all necessary details for an agent to understand what the tool returns and how to use the result.

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

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

Schema coverage is 100%, but the description greatly enriches both parameters: for type it explains the enum values, for value it details accepted formats (ticker, CIK, name for company; brand/generic for drug) and what the tool returns (ticker, CIK, RxCUI, etc.), far exceeding 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 a canonical identifier, with specific examples like ticker, CIK, RxCUI. It distinguishes from siblings by mentioning that other tools require IDs as input, implying this is the lookup step.

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 says 'Use FIRST whenever you have a name but need an ID,' providing explicit guidance on when to use this tool. It also lists supported entity types and their outputs, helping the agent decide when to call it.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds how it works (probes, ranks) and what it returns (score, confidence, density). No contradictions, but doesn't discuss potential side effects like API key requirements or rate limits.

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

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

Three sentences: action, method, use case. Every sentence adds value. No redundancy. Front-loaded with core purpose.

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

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

Given no output schema, the description adequately explains the return format (ranked list with fields). It covers the tool's scope and limitations (2-8 entities mentioned in schema). Could mention behavior when API key is missing for anthropic model, but not critical.

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 does not add information beyond what the schema provides for parameters; the schema already explains the 'first entry' treatment and allowed values.

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

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

The description clearly states it compares AI visibility across multiple entities, mentions probing with ai_visibility_check, and ranks results. It distinguishes itself from siblings like ai_visibility_check (single entity) and compare_entities (generic comparison) by focusing on AI presence metrics.

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 a concrete use case: 'competitive AI-marketing audits' and quotes a relevant question. Implicitly suggests using ai_visibility_check for single entities, but does not explicitly list alternatives or when to avoid 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 indicate readOnly, openWorld, idempotent, non-destructive. Description adds behavioral context: fans out across two services, bundlephobia first measurement can take 5-30s, sources_failed lists timeouts, partial failures degrade gracefully. No contradictions.

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

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

Well-structured: first sentence states purpose, then sources, usage, output summary, scope, failure handling. Front-loaded with key verb and resource. Every sentence adds value despite 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?

No output schema exists, so description must cover output format. It does: summary block with specific fields, per-advisory detail, links, and recent alternatives. Also covers ecosystem limitation and partial failure behavior.

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

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

Schema describes both parameters (package, version) with 100% coverage, including default behavior. Description adds minimal extra parameter info (scoped packages accepted) but confirms schema details. Baseline 3 is appropriate as schema does the heavy lifting.

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

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

The description clearly states the tool performs a composite check for npm packages combining deps.dev and bundlephobia data, answering questions about safety, popularity, and size. It distinguishes from siblings by noting other ecosystems use deps.dev:version directly.

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

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

Explicitly states when to use: when asked 'is X safe/popular/small' or 'what does adding lodash cost me'. Also specifies when not to use: for non-NPM ecosystems (PyPI/Maven/Cargo/Go) use deps.dev:version directly.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds technical details (BGE-base-en, 500-char windows, 200K cap with truncation flag) and return format (offsets, similarity), going well beyond annotations.

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

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

Single well-structured paragraph, front-loaded purpose, no wasted words. All technical details are relevant and earned.

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

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

No output schema, but description fully explains return values (passages with offsets and scores), cap, encoding, and pairing. Complete for a single-tool search operation.

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

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

Schema coverage 100%, baseline 3. Description adds example queries for 'query' and clarifies return structure (offsets, similarity). Provides more context than schema alone.

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

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

Clearly states 'semantic search INSIDE a fetched record' with specific verb and resource. Distinguishes from siblings by emphasizing context-saving and offset-based verification, and explicitly pairs with ask_pipeworx_grounded.

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

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

Explicitly says 'Use when the record is too big to cram into the prompt' and explains benefits. Mentions pairing with ask_pipeworx_grounded, providing clear context. No 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?

Adds significant behavioral details beyond annotations: requires OAuth, returns id, delivery channel behaviors (feed always on, email/sms/webhook specifics, webhook auto-disable, sms cap). No contradictions with annotations.

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

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

Well-structured with front-loaded purpose, requirements, types, delivery. Each sentence adds value, but could be slightly more concise.

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

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

Covers return value, requirements, type-specific params, delivery channels. Missing error scenarios or duplicate behavior, but idempotent hint covers that. Mostly complete.

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

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

Schema coverage is 100%, but description adds extensive examples and clarifies structure for each type and delivery channel, e.g., items array for sec_8k, webhook secret handling.

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 creates a proactive monitoring subscription, returns subscription id. Differentiates from sibling tools like list_subscriptions and unsubscribe. Provides examples of supported types.

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

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

Specifies when to use (proactive monitoring), requirements (Pipeworx OAuth), and lists supported types with examples. Does not explicitly state when not to use, but context is clear.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds value by explaining return content (category-bucketed example questions with tool+argument shapes), that it draws from live catalog, and effect of topic parameter. No contradictions.

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

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

Description is moderately long but well-structured, starting with common queries, then explaining return format and usage. Every sentence adds value. Could be slightly more concise but still effective.

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

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

For a simple tool with one optional parameter and no output schema, the description is very complete: it covers purpose, return content, usage, and when to use it. No gaps given the tool's role as an onboarding entry point.

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 the single optional parameter described. Description adds examples of topic values ('finance', 'pharma', 'betting') and explains focusing effect, going beyond schema description. Good value 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?

Description explicitly states it's an onboarding entry point to discover what questions to ask Pipeworx, listing example categories and return format. Title 'What Can I Ask Pipeworx?' clearly conveys purpose. Siblings like ask_pipeworx are for actual querying, distinguishing this tool.

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

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

Explicitly says 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools...' providing clear context for use. No explicit when-not-to-use, but the guidance is clear and specific.

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

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

Annotations declare read-only, open world, idempotent, non-destructive. Description adds that data is one row per fiscal year, covers 2001–2021, and responses include vintage, providing behavioral context beyond annotations.

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

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

The description is front-loaded with the main purpose, includes examples and alternatives, and every sentence adds value without unnecessary fluff.

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

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

Given no output schema, the description adequately covers data source, time range, granularity, response contents, and alternative tool, making it fully complete for a simple count tool.

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

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

Schema coverage is 100% with clear parameter descriptions. The description adds context about response structure (fiscal year, vintage, shares) but does not significantly enhance parameter understanding beyond schema.

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

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

The description clearly states the tool counts vehicles registered in Texas with breakdowns by type and provides example questions. It distinguishes itself from the California breakdown tool mentioned in the description.

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

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

The description explicitly states the tool answers specific questions about Texas registrations and directs users to ca_dmv_vehicle_registrations for granular data, providing clear when-to-use and when-not-to-use guidance.

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

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

Discloses that the row is deactivated not deleted and historical events remain available via recent_alerts, adding context beyond the annotations (which only indicate non-destructive).

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

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

Two concise sentences, front-loaded with purpose, no unnecessary words.

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

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

Given the tool's simplicity (single required param, no output schema), the description fully explains behavior, ownership, and side effects.

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

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

Schema coverage is 100% with clear parameter description. The description adds no additional semantic meaning beyond what the schema provides.

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

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

The description uses specific verb 'Cancel' and resource 'subscription by id', clearly distinguishing from sibling tools like subscribe and list_subscriptions.

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

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

States ownership enforcement ('you can only cancel your own subscriptions'), providing clear usage context. Does not explicitly mention alternatives or when not to use, but the constraint is sufficient.

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

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

Annotations already indicate readOnly, openWorld, idempotent, non-destructive behavior. The description adds significant behavioral insight: it details the two processing paths (structured SEC vs grounded pipeline), explains the verdict types, and notes that it replaces multiple sequential calls. No contradictions with annotations.

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

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

The description is well-structured: starts with example triggers, then usage guidance, then internal processing details, then return value summary. While slightly verbose, every sentence adds value. Front-loaded with key purpose indicators.

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

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

Given no output schema, the description thoroughly explains return values (verdict, actual value with citation, reasoning). It covers two distinct processing paths, parameter effects, and the tool's efficiency advantage. No gaps for the intended use case.

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

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

Schema coverage is 100% (both parameters described). Description adds context: tolerance_pct overrides implied tolerance, default is 5% cap, and provides claim example. This enhances understanding beyond the schema definitions.

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: verifying factual claims using natural language input. It provides multiple example phrases ("Is it true that…"/"fact check") and describes the two verification paths. However, it does not explicitly differentiate from sibling tools like deep_research or ask_pipeworx_grounded, which may handle similar 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 explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct.' This is clear usage context. It also distinguishes between financial claims (SEC EDGAR path) and other claims. However, it does not explicitly state when not to use the tool or suggest alternative tools.

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