Pipeworx

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: cost implications of using Anthropic (BYO key, direct billing) and that it returns per-model scores and a combined view. 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 concise with two sentences front-loaded with the main action. Every sentence adds value, no wasted words. Information is efficiently packed without being verbose.

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

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

Given no output schema, the description adequately explains high-level return structure (per-model and combined view). It covers tool action, parameters, cost implication, and usage context. Minor gap: no detail on what 'signals' or 'confidence' mean, but overall sufficient for 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%, baseline is 3. The description adds meaning beyond schema by explaining the 'models' parameter values ('workers-ai' and 'anthropic') and the '_apiKey' requirement for Anthropic, including the cost implication. This enriches parameter understanding.

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

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

The description clearly states the tool's purpose: probing LLMs for visibility of a business/brand/product/topic and scoring it 0-100 per model. It distinguishes from siblings by focusing on LLM probing and AI-marketing audits, with specific details on default model and BYO key.

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

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

The description gives clear context for when to use the tool (AI-marketing audits, pre-launch brand checks, competitive monitoring) and explains parameter usage (default model, optional Anthropic key). However, it does not explicitly exclude scenarios or compare to alternative sibling tools.

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

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

Annotations already cover readOnly, openWorld, idempotent, and non-destructive hints. The description adds behavioral context about routing to 3,745 tools and returning citations, which is valuable. 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 effective and front-loaded with the key usage guidance 'PREFER OVER WEB SEARCH'. It includes examples but is slightly lengthy; could be trimmed slightly 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?

Despite no output schema, the description explains the return format as a structured answer with citation URIs. This is sufficient for the tool's complexity, and no gaps are evident.

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 parameters are well-documented as aliases for 'question'. The description adds minimal extra meaning beyond what the schema provides, but the schema itself is clear. 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 routes questions to a vast set of tools/sources for factual data, distinguishing it from web search and siblings. It uses specific verbs like 'routes', 'fills arguments', and 'returns structured answer'.

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

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

The description explicitly says 'PREFER OVER WEB SEARCH' and lists many question types, providing clear when-to-use guidance. It also gives concrete examples like 'current US unemployment rate'.

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

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

Annotations already mark the tool as read-only, idempotent, and non-destructive. The description adds significant behavioral details: it routes through 3,745 tools, returns a structured response with refusal reasons, and guarantees only the tool result is used. No contradictions with annotations.

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

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

The description is front-loaded with key information and each sentence adds value. However, it is slightly lengthy; a bit more conciseness would improve it. Still, well-structured.

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

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

Given the complexity (no output schema, many siblings), the description is remarkably complete. It covers output structure, refusal reasons, and behavioral guarantees, leaving no critical gaps for tool selection and invocation.

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

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

Schema coverage is 100% with descriptions for each parameter. The description mentions 'question' but adds no further semantic detail beyond the schema. According to guidelines, baseline 3 is appropriate here.

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: 'Hallucination-resistant answer mode for high-stakes reads'. It explains that it extracts answers only from tool results, contrasting with the sibling ask_pipeworx. The verb-resource pair is specific and distinctive.

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: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts.' Also advises preferring ask_pipeworx for casual lookups and notes the extra LLM call cost. This provides clear when-to-use and when-not-to-use context.

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

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

The description is highly transparent beyond annotations. It details internal processes (market resolution, classification, fan-out, evidence packet), safety mechanisms (low-confidence short-circuit, closed market handling, wide-spread illiquidity), and resolution-rule risk. No contradictions with annotations.

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

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

The description is long but well-structured with labeled sections (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, etc.). Each section adds necessary detail; however, some redundancy could be trimmed (e.g., resolution-rule risk appears twice). Overall, it is thorough and front-loaded with the main 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 comprehensively explains the response structure (market, analysis, evidence, resolver contract, parent event, news fields) and edge cases (low confidence, closed markets, wide spreads, cancellation rules). It covers all necessary context for correct tool usage.

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

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

Schema coverage is 100%, so the schema already documents parameters. The description adds value by explaining the difference between 'quick' and 'thorough' depth, the flexible market input formats, and the behavior of 'include_raw' in terms of response size and use cases. This goes beyond the schema's 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: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies the core action (research), resource (Polymarket bet), and distinguishes it from siblings by its specialized focus on bet research with data fan-out.

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 usage scenarios: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' Also includes examples of when not to use, such as closed or dead markets that return specific statuses, and warns about low-confidence resolutions.

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, so the bar is lower. The description adds valuable behavioral details: off-calendar fiscal year handling, specific financial and drug data fields, and sorting by primary metric. 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 a single dense paragraph but is well-organized and front-loaded with trigger phrases. It uses emphasis (ALL CAPS) for key instructions. Could be slightly more structured with bullet points, but it remains concise given the amount of information conveyed.

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

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

No output schema is provided, so the description must describe return values. It states 'Returns paired data + pipeworx:// citation URIs per entity.' It covers the key aspects: what data is pulled for each type and sorting behavior. It addresses the core needs for a comparison tool.

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

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

Schema coverage is 100%, but the description adds significant meaning beyond the schema. It explains that 'company' type uses tickers/CIKs and pulls specific financial data, while 'drug' type uses drug names and pulls adverse-event counts, FDA approvals, trial counts. It also specifies the range 2-5.

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 includes explicit trigger phrases like 'Compare X and Y' and 'which is bigger / better,' and distinguishes from siblings by stating 'ALWAYS PREFER over sequential single-pack 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 instructs to prefer this tool over sequential lookups when comparing entities, and provides example queries. It could state when not to use it, but given sibling tools like entity_profile, the contrast is implied.

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 safe behavior (readOnlyHint, idempotentHint, openWorldHint). The description adds that it never invents facts (returns gaps[]), expects 15-60s, and requires authentication. However, it does not specify the exact output format despite claiming a 'structured findings packet'—a minor gap given no output schema.

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 slightly verbose (4+ sentences). The most critical info (purpose, when to use, requirements) is front-loaded. Could be tightened by removing redundant phrases like 'the facts arrive pre-verified' 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?

Despite lacking an output schema, the description explains what the tool returns (evidence, confidence, source, gaps) and its non-inventive behavior. For a research tool with complex behavior, this is sufficient to set accurate expectations. All relevant aspects are covered.

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

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

Schema covers 100% of parameters with descriptions, but the description adds practical context: depth values are explicitly mapped to facet counts (quick=3, standard=5, thorough=8) and the paid plan requirement for thorough. This enhances usability 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 'grounded multi-source research in ONE call' and explains the decomposition, parallel routing, and evidence extraction. It distinguishes itself from sibling 'ask_pipeworx' for single lookups. Verb+resource+scope is specific and 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?

Explicitly advises using for broad or multi-part questions and directs to 'ask_pipeworx' for single lookups. Also mentions requirements: Pipeworx account and paid plan for thorough depth. Provides clear when-to and when-not-to guidance.

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

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

Annotations already provide readOnlyHint=true, idempotentHint=true, destructiveHint=false. Description adds that results are directly callable with 'names, descriptions, and full input schemas (with curated examples)', which is helpful beyond annotations.

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

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

Five sentences, front-loaded with purpose, no wasted words. Each sentence adds value: purpose, domain list, output details, and when to call.

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, description fully explains return format. Low complexity (6 params, no enums, read-only) means description is complete and sufficient 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 description coverage is 100%; description adds alias context for query parameter but does not significantly enhance meaning beyond schema. Baseline 3 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?

Description clearly states 'Find tools by describing the data or task' and lists specific domains (SEC filings, financials, etc.). It distinguishes itself from sibling tools (specific operations) by emphasizing it returns top-N tools with full schemas for direct calling.

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 'Call this FIRST when you have many tools available and want to see the option set'. Lists use cases but does not explicitly exclude alternatives like search_mcp_directory, though context implies its unique role.

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, openWorldHint, idempotentHint) are present. The description adds extensive behavioral detail: fans out across multiple data sources, lists returned fields, notes USPTO API sunset and soft-fall behavior, and explains input constraints. 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 detailed and structured, starting with examples, then purpose, usage guidance, and output specifics. While slightly verbose, every sentence adds value for understanding the tool, making it appropriately sized for the complexity.

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

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

Given the tool's complexity (multiple data sources, no output schema), the description is thorough. It explains the response structure, data sources, limitations (USPTO sunset), and input constraints. An agent would have all necessary context to invoke and interpret results.

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

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

Schema covers 100% of parameters with clear descriptions. The description reinforces by providing concrete examples (e.g., 'AAPL', '0000320193') and clarifying that names are not supported. Parameter meaning is fully explained both in schema and description.

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

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

The description clearly states the tool provides a 'full cross-source profile of a US public company in ONE parallel call' and gives multiple example queries. It distinguishes itself from chaining single-pack lookups, 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?

Explicitly advises 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' Also specifies supported inputs (ticker or zero-padded CIK) and directs users to resolve_entity for names, 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?

Annotations already indicate destructiveHint=true and idempotentHint=true. The description adds that deletion is for clearing data, but does not elaborate on idempotency or other side effects beyond what annotations provide.

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

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

The description is two sentences, front-loaded with the main action, and contains no superfluous information. Every sentence adds value.

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

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

Given the tool's simplicity (single parameter, no output schema), the description covers core purpose, usage guidelines, and relationships with sibling tools. No critical gaps are present.

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

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

Schema coverage is 100% with a clear description for the 'key' parameter. The tool description does not add additional meaning or constraints beyond the schema, meeting the baseline for high 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 'Delete a previously stored memory by key,' specifying the exact action and resource. It distinguishes from sibling tools like 'remember' and 'recall' by implying a deletion 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?

The description provides explicit scenarios for use: stale context, task completion, or clearing sensitive data. It also suggests pairing with 'remember' and 'recall,' but does not specify 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?

The description adds behavioral details beyond annotations: it fetches the page, extracts title/description/key links, and emits standard markdown format. It also specifies the output is a single text blob, which is not covered by 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 front-loaded with the main purpose. Every sentence adds value, covering what it does, how it works, and use cases without superfluous details.

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

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

Given no output schema, the description fully explains the output format (single text blob for site-root/llms.txt). It covers purpose, process, and usage, making it complete for a simple tool.

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

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

Schema description coverage is 100%, so baseline is 3. The description does not add new semantics beyond what's in the schema; it mentions fetching the page (implicitly the URL) but does not elaborate on max_links beyond the schema's description.

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

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

The description clearly states the tool generates a production-ready llms.txt file for a URL, specifying the verb 'generate' and the resource 'llms.txt file'. It distinguishes from sibling tools like scan_competitor_ai_presence by focusing on file generation rather than scanning presence.

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

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

The description lists three specific use cases (getting a client's site indexed, drafting for own project, auditing competitor view), giving clear context for when to use. However, it does not explicitly mention when not to use or provide alternative tools.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is clear. The description adds that it returns connection details and gateway URLs, but provides no additional behavioral context beyond what annotations indicate.

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 long, front-loads the purpose, and contains no filler. Every sentence earns its place, providing essential information without redundancy.

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

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

For a simple tool with one parameter, high schema coverage, and an output schema present, the description adequately states the purpose and use case. It could specify the output format more, but the existence of an output schema mitigates this. Overall, it's complete enough for effective tool selection.

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

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

Schema description coverage is 100% with a clear parameter description for 'slugs'. The tool description does not reference the parameter explicitly, so it adds no extra meaning beyond the schema. Baseline score of 3 is appropriate given 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 clearly states the action ('Get MCP setup instructions'), the resource ('for connecting to Pipeworx packs'), and the output ('Returns connection details and gateway URLs'). It effectively distinguishes from sibling tools like list_packs and get_pack_tools by focusing on setup configuration.

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 to configure your environment,' which gives a basic usage context but does not explicitly state when not to use this tool or mention alternative tools (e.g., list_packs for listing packs). The guidance is clear but lacks exclusions or comparisons.

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, idempotentHint=true, and destructiveHint=false, so the tool is safe and non-destructive. The description adds value by specifying the return content (names, descriptions, parameters, requirements), giving 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?

Two sentences, front-loaded with the core purpose, no extraneous information. Each sentence serves a clear role: stating the function and providing usage 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 has low complexity (single required parameter, no nested objects, output schema exists). The description concisely covers what the tool does, what it returns, and when to use it, making it fully adequate 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 coverage is 100%, and the single parameter 'slug' is already well-described in the schema. The description only reiterates the examples, adding no new semantic depth. Baseline 3 is appropriate.

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

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

The description clearly states the tool retrieves tool definitions for a specific pack, with examples ('weather', 'stocks'). It distinguishes itself from sibling tools like 'list_packs' and 'search_packs' by focusing on retrieving definitions for a given pack, not listing or searching packs.

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

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

The description explicitly says to use it 'before calling a tool to verify its interface', providing clear usage context. While it doesn't list alternatives or when not to use, the sibling tool names and tool purpose implicitly guide appropriate use.

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

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

Annotations already indicate readOnly, idempotent, non-destructive behavior. The description adds detail on the specific returned data (pack count, active tool count, alerts) beyond the annotations, enhancing transparency without contradiction.

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

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

Three sentences with no wasted words. Front-loaded with the action ('Check Pipeworx platform health and availability') and ends with usage advice. Ideal 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 zero parameters, strong annotations (readOnly, idempotent, non-destructive), and presence of an output schema, the description fully covers the needed context: purpose, return values, and usage timing.

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?

No parameters exist, so schema coverage is 100%. The description adds value by explaining what the output contains, even though no parameter semantics are needed.

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

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

The description clearly states it checks platform health and availability, returns specific data (pack count, active tool count, service alerts), and explicitly says to verify system status before operations. The name and title reinforce the purpose succinctly.

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 to verify system status before operations', indicating when to employ the tool. Lacks explicit 'when not to use' or alternative tools, but the context is clear and sufficient.

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

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

Annotations already provide readOnlyHint=true, idempotentHint=true, destructiveHint=false, covering safety and idempotency. Description adds filtering capability by category but doesn't disclose additional behaviors like pagination or response limits. With annotations present, this level of detail is adequate.

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 filler. Front-loaded with purpose, followed by return values and usage intent. 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 an output schema present, the description need not detail return structure, but it does mention key fields. The optional filter parameter is explained. No gaps remain for a list tool of this 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?

Schema description coverage is 100%, so the schema already documents the category parameter and its possible values. The description mentions 'Filter by category' but adds no new semantic detail beyond the schema, thus baseline score 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?

Description clearly states the verb 'Browse' and resource 'Pipeworx packs', specifies return fields (names, categories, tool counts, gateway URLs), and distinguishes from siblings like search_packs by emphasizing discovery and exploring availability.

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

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

Explicitly states when to use ('discover data sources or explore what's available'), which guides selection among similar list/search tools. No explicit when-not-to-use, but context from sibling names provides sufficient distinction.

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, and non-destructive hints. The description adds behavioral details: it lists specific return fields (id, type, params, created_at, etc.) and mentions the optional include_inactive parameter, which goes beyond annotations.

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

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

Two sentences with no superfluous content. The main purpose is front-loaded, and every sentence provides 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 no output schema, the description lists return fields explicitly. It covers purpose, usage, and parameter behavior well for a simple tool with one optional parameter.

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

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

Schema coverage is 100% with the single parameter include_inactive having a description. The description does not add much parameter-level detail beyond the schema, but it contextualizes that the default is active-only. Baseline 3 is appropriate.

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

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

The description states 'List the caller's active subscriptions' with a specific verb and resource. It distinguishes from siblings like subscribe and unsubscribe, which are the only similar 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 provides explicit use cases: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' It does not explicitly exclude scenarios, but the guidance is clear and helpful.

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

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

The description adds behavioral context beyond the annotations, such as 'Rate-limited to 5 per identifier per day' and 'Free; doesn't count against your tool-call quota.' It also discloses that the team reads digests daily and feedback affects the roadmap. 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 at 5 sentences, front-loaded with the core purpose immediately. Every sentence adds value: purpose, usage scenarios, formatting instructions, team response time, rate limits, and quota info. No redundant or unnecessary text.

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

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

For a feedback tool with no output schema, the description covers usage, behavior, and constraints thoroughly. It lacks explicit mention of what the return value looks like (e.g., acknowledgment), but that is minor given the tool's simplicity and the context of other sibling tools.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds the guidance to 'describe the issue in terms of Pipeworx tools/packs — don't paste the end-user's prompt,' but the schema already includes descriptions for `context` and `message` that convey similar expectations without additional semantic nuance.

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 clear verb and resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It distinguishes itself from sibling tools, which are all query/action tools, by being the explicit feedback submission tool.

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

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

The description provides specific usage contexts: 'Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' It also instructs to describe issues in terms of Pipeworx tools/packs and not paste end-user prompts.

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?

Goes beyond annotations by explaining data source (CF analytics-engine), no PII, caching window (5min-1h), and self-aggregating nature. No contradiction with existing readOnlyHint, idempotentHint, destructiveHint.

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

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

Three sentences, front-loaded with main output. Every sentence adds distinct value. No filler or redundant information.

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

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

Complete for a simple read-only tool with one optional parameter and no output schema. Covers output structure, data source, privacy, caching, and usage scenarios.

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 'window' parameter with enum values. Description adds practical semantics: shorter windows for hot trends, longer for steady-state demand. Provides guidance beyond schema.

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

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

Clearly states it returns top tools, packs, and call volume over a window. Uses 'returns' and 'calling' as specific verbs. Distinguishes from siblings like search_packs and discover_tools by focusing on aggregate trending signal.

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 concrete use cases (discovering hot topics, confirming canonical choices, aligning use cases). Lacks explicit when-not-to-use or alternatives, but context makes it clear this is for trend discovery only.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false, which the description complements by detailing internal logic (walking child markets, similarity thresholds, partition filters, fill check) without contradiction.

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

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

The description is well-structured with the requirement front-loaded. Every sentence adds value, covering modes, filters, response format, and fill check without unnecessary repetition.

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

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

Without an output schema, the description fully explains the response structure (opportunities array, partition_check object). It covers edge cases (missing args, low similarity, placeholder filtering, fill check viability) and integrates with a sibling tool.

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

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

Schema description coverage is 100%, but the description adds significant meaning: clarifying event vs topic roles, providing usage examples, and explaining how each parameter triggers different processing logic.

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 finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes two modes (event and topic) with specific examples, differentiating it from sibling tools like polymarket_edges and 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?

It explicitly states that one of event or topic is required and calling with no args fails. It recommends event for specific markets and topic for cross-event scanning, and mentions polymarket_fill_risk for custom sizing, providing clear when-to-use guidance and alternatives.

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

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

The description extensively covers behavioral aspects beyond annotations: it explains internal models (crypto_price, news_momentum, partition_overround, concentrated_longshot), response structure (by_segment, diagnostics), caching behavior ('Cached 1h at the KV level'), and edge computation details (edge_pp_net, kelly_fraction). No contradictions with annotations.

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

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

The description is lengthy but well-structured, with clear segments (model families, knobs, response top-level). Every sentence adds value, though some technical details (like specific alpha values) could be moved to external documentation. It is front-loaded with the main 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?

The description is completely self-contained, covering the entire tool behavior without reliance on output schema. It explains response segments, diagnostic fields, and filter logic. Given the complexity (9 parameters, no output schema), the description is exceptionally thorough.

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 substantial context beyond the schema: for example, it explains why min_partition_leg_kelly is needed for partitions, describes Polymarket fee structure in slippage_pp, and provides concrete examples for min_liquidity. This significantly aids parameter understanding.

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

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

The description clearly states the tool scans Polymarket markets to find opportunities where Pipeworx data disagrees with market price. It uses a specific verb-resource pair and explicitly mentions the use case 'what should I bet on today', distinguishing it from sibling tools like polymarket_arbitrage or polymarket_edge_tracker.

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 the intended use case ('agents discover opportunities without paging hundreds of markets') and details about tradeable-edge knobs (min_liquidity, max_spread_pp) that filter realizable opportunities. However, it does not explicitly exclude alternative tools or clearly state when not to use this tool, lowering the score from 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?

The description goes well beyond the annotations (which already declare readOnly, openWorld, idempotent). It details the exact response structure (tracked, expired, snapshot_dates), explains how trend and decay are computed, discloses limitations (60-day TTL, daily closes, gaps from cache misses), and notes that decay is not intraday. No contradiction with annotations.

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

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

The description is dense but efficiently packed with information. It is front-loaded with a motivating question and clearly delineates response fields and limits. While it is long, every sentence serves a purpose, and the structure is logical. Could be slightly more concise but still high quality.

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 is remarkably complete. It explains all response components (tracked, expired, snapshot_dates) including sub-fields like first_seen, trend, decay_pp_per_day, and lifespan_days. It also covers edge cases such as data gaps and TTL limits. This gives the agent full understanding of what to expect.

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

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

Since schema coverage is 100% with descriptions for both parameters, the baseline is 3. The description adds value by explaining the implication of gaps in snapshot dates ('snapshots are written when polymarket_edges runs on a cache-miss, so gaps mean nobody scanned that day'), which provides context beyond the schema's clamp and default 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 the tool's purpose: 'Edge persistence and decay telemetry' built from daily snapshots. It answers a specific question ('how long has this edge existed and is it shrinking?') and distinguishes itself from sibling tools like polymarket_edges by focusing on temporal analysis rather than just listing edges.

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

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

The description provides clear context on when to use this tool: when evaluating the quality of an edge based on its history. It contrasts fresh vs old edges. However, it does not explicitly state when not to use it or mention alternatives like polymarket_edges, which could be more suitable for just listing current edges.

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

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

Annotations already mark as safe (readOnlyHint, idempotentHint, destructiveHint false). The description adds detailed behavioral info: walks the ladder, returns specific fields per mode, and warns of forced directional risk. No contradiction with annotations.

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

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

Description is dense but well-organized: purpose, mode requirements, single-market details, basket details, usage guidance. Every sentence adds value. Somewhat lengthy but necessary for the complexity.

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

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

Very complete given no output schema. It enumerates all return fields for both modes (e.g., top_of_book, vwap_fill_price, capture_ratio, thin_legs). Also explains the real-world motivation (dominant loss mode). No gaps.

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

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

Schema coverage is 100% (baseline 3). The description adds meaning by explaining interpretation of size_usd for both modes (settlement notional for basket), default side determination for basket (auto), and that market/event are mutually exclusive. It clarifies beyond what 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 'Realizable-vs-theoretical edge check against live CLOB order-book depth' and distinguishes between single-market and basket modes. It explicitly connects to sibling tools by advising use before polymarket_arbitrage or polymarket_edges trades.

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: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. Also explains why based on partial fill risk and theoretical overround, and specifies required parameters 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?

Annotations (readOnly, idempotent, etc.) are present, but the description adds significant behavioral context: it details safety fields (compatibility_warning cases, temporal_alignment) and explains why spreads might be meaningless. No contradiction with annotations.

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

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

The description is longer but well-structured with clear sections (TWO MODES, RESPONSE, SAFETY FIELDS). Every sentence adds necessary information. A slight reduction in verbosity could improve conciseness, but the structure compensates.

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

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

Despite lacking an output schema, the description fully explains the response structure (leg prices, top spreads, safety fields). It covers all relevant aspects for a 3-parameter tool with no required params and no enums.

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

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

The input schema has 100% coverage, but the description adds value by explaining the two operation modes (topic vs explicit) and how parameter overrides work. It also provides examples and clarifies the behavior of the topic 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 purpose: computing cross-venue spreads between Kalshi and Polymarket. It distinguishes itself from sibling tools like polymarket_arbitrage by focusing on the same question across venues and explaining the two modes (topic shortcuts and explicit pairing).

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

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

The description explicitly guides when to use the topic mode vs explicit mode. It warns that most pre-mapped topics currently return compatibility_warning, and provides criteria for when spreads are meaningful (temporal alignment, compatible bet shapes). This helps the agent decide appropriately.

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 behavioral context (omitting key lists all, scoped retrieval) 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?

Three concise sentences with front-loaded action and no wasted words. Each sentence adds necessary 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?

For a simple retrieval tool with no output schema, the description fully explains behavior, scoping, and return expectations (value or list of keys).

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; description adds value by explaining the optional key's effect ('omit to list all keys') beyond the schema description.

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

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

The description clearly states the tool retrieves a saved value or lists all keys, distinguishing it from 'remember' and 'forget' siblings. It uses specific verbs ('retrieve', 'list') and resource ('value saved via remember').

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

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

Explicitly tells when to use ('look up context stored earlier') and provides alternatives ('pair with remember to save, forget to delete'). States scope ('scoped to your identifier').

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, non-destructive. Description adds return field details, mark_read side effect, and poll-friendliness, enriching behavioral context without contradiction.

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

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

Concise, front-loaded with action, 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?

Covers return fields, filter, mark_read, and alternative endpoint. Missing pagination hints beyond limit parameter, but otherwise complete for a read-only tool.

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

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

Schema coverage is 100%, so baseline 3. Description adds example for type ('sec_8k'), clarifies since as ISO timestamp, and explains mark_read behavior, providing extra value beyond schema.

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

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

Clearly states it pulls fired events from subscription feed. Verb 'Pull' and resource 'fired events' are specific. No explicit differentiation from siblings, but it's distinct from similar tools like 'recent_changes'.

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 usage context (filtering, mark_read, polling) but lacks explicit when-to-use vs alternatives. Mentions an alternative REST endpoint but no exclusion 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?

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds significant behavioral detail beyond these: it explains the fan-out to multiple sources, the fallback from GDELT to GNews on errors, and the soft-fail for USPTO due to API sunset. 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 relatively long but efficient: front-loaded with example queries, then details on sources, parameter guidance, and sibling differentiation. Every sentence contributes value, though a bit dense. It could be slightly trimmed without losing clarity, but overall well-structured.

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

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

Given the complexity (multiple sources, parameter constraints) and no output schema, the description adequately covers the return structure ("structured changes[] grouped by source + total_changes count + pipeworx:// citation URIs") and the full parameter semantics. It feels 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 schema already documents each parameter. The description adds meaning by explaining the purpose of `since` in context (window start), providing example values, and clarifying that `type` only supports "company". This goes beyond the schema but does not fully replace the need for 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 uses concrete example queries ("What's new with X", "latest on Y") to clarify the tool's function as a change feed for a company over a recent time window. It distinguishes from sibling tool entity_profile by explicitly stating when to use the alternative, ensuring the purpose is well-defined and not confused with other tools.

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

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

The description provides explicit usage guidance: when to use (the example queries), and when not to use ("Use entity_profile instead when you want the static profile..."). It also offers parameter guidance such as suggesting "30d" for `since`. This clear differentiation helps an agent choose correctly.

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

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

Annotations already indicate idempotentHint=true. The description adds valuable context beyond annotations: memory is scoped by identifier, persistent for authenticated users, and lasts 24 hours for anonymous sessions. No contradictions.

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

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

The description is concise (3 sentences) and front-loaded with the essential purpose. Every sentence adds value without redundancy.

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

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

Given the simple parameter set (2 required string params), no output schema, and informative annotations, the description provides a complete picture. It explains scope, persistence, and pairing with sibling tools.

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

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

Schema description coverage is 100%, so the schema already documents both parameters. The description provides illustrative examples (e.g., 'subject_property', 'target_ticker') but does not add significant semantic depth 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's purpose: saving data for later reuse across conversations or sessions. It uses specific language like 'discover something worth carrying forward' and distinguishes from sibling tools recall and forget.

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

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

The description provides explicit guidance on when to use the tool (when discovering something worth carrying forward) and explicitly mentions alternative tools: 'Pair with recall to retrieve later, forget to delete.'

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. The description adds valuable behavioral context: internal cascading through multiple endpoints, auto-disambiguation for companies, and specific return formats (ticker, CIK, RxCUI, citation URIs). No contradictions.

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

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

The description is well-structured: starts with examples, then a clear one-line purpose, then detailed type descriptions. Every sentence adds value, though it could be slightly more concise 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?

Given no output schema, the description fully explains return values for each type (ticker, CIK, company_name, citation URI for company; RxCUI, ingredient, brand, citation for drug). It also covers auto-disambiguation and internal cascading, making the tool's behavior complete 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%, so baseline is 3. The description significantly enhances understanding by explaining that for 'company' type the value can be ticker, CIK, or name with auto-disambiguation, and for 'drug' it accepts brand or generic. It also describes what each type returns, far exceeding the bare 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 opens with concrete examples that map user intents to the tool's purpose, then explicitly states 'resolve a user-spoken NAME to the canonical/official identifier other tools require as input.' It distinguishes itself from siblings by detailing the specific types (company, drug) and what it returns for 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?

The description gives a strong usage signal: 'Use FIRST whenever you have a name but need an ID.' It also suggests this tool replaces 2-3 manual lookups, providing clear context. However, it does not explicitly state when not to use it or mention alternative sibling tools.

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

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

Annotations already indicate readOnly, idempotent, and non-destructive behavior. The description adds context: it uses ai_visibility_check internally, treats the first entity as the subject, and outputs a ranked list with score, confidence, and signal density. This goes beyond what annotations provide.

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

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

The description is concise—4 sentences—with the core purpose first, then process, usage example, and return value. No extraneous 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?

The description covers purpose, process, usage context, and return value. It lacks details on error handling or limits, but for a read-only comparison tool with good annotations, it is sufficiently 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 description coverage is 100%, so the description's parameter details (like entities being 2-8 and first treated as subject) are already in the schema. The description does not add significant new meaning beyond the schema.

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

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

The description clearly states the tool compares AI visibility across multiple entities, probes each with ai_visibility_check, and ranks results. It differentiates from the sibling tool ai_visibility_check by specifying side-by-side comparison.

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

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

The description provides explicit use cases (competitive AI-marketing audits) and an example question. However, it does not discuss when to use this tool over other sibling comparison tools like compare_entities, nor does it mention 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?

Beyond annotations (readOnlyHint, idempotentHint), the description details behavioral traits: partial failures degrade gracefully with sources_failed field, bundlephobia's first measurement can take 5-30s, and the output includes specific fields and alternative versions. This adds significant value for the 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?

Front-loaded with the main purpose, but slightly verbose with technical details. Every sentence adds value, but could be tightened 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?

Without an output schema, the description fully explains the return structure (summary, advisories, links, alternative versions) and handles edge cases like partial failures and timing, making it self-contained and 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?

Input schema covers 100% of parameters with descriptions; description adds nuance (scoped packages accepted, version defaults to latest) and clarifies usage, but schema already provides the core meaning.

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

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

The description clearly states the tool is a composite check for evaluating npm packages, combining multiple data sources (deps.dev and bundlephobia) to answer questions like 'is X safe/popular/small' or 'what does adding lodash cost me'. It distinguishes itself from sibling tools by its unique composite, npm-specific focus.

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

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

Explicitly states when to use ('whenever an agent asks...') and when not to ('NPM ecosystem only in v1; PyPI/Maven/Cargo/Go fall under deps.dev:version directly'), providing clear context for 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 indicate safe read operation; description adds returns community and hosted servers but no further behavioral details like pagination 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?

Two sentences, front-loaded with purpose, no wasted words.

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

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

Given good annotations, full schema, and output schema, the description is complete: explains what it searches and returns, and usage 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?

Schema description coverage is 100%, so description does not add extra meaning 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?

Description clearly states it searches MCP servers by use case, with examples ('database', 'email', 'calendar'), and distinguishes from Pipeworx internal tools via 'Use to find tools beyond Pipeworx'.

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

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

Provides clear context on when to use (finding external tools) but does not explicitly exclude alternatives or mention siblings like 'discover_tools'.

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

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

Annotations already provide readOnlyHint, idempotentHint, and destructiveHint, so the description does not need to repeat those. It adds value by stating the search scope (names, descriptions, tools) and that it returns details, which is beyond the basic 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 extremely concise at two sentences, with the purpose front-loaded. No unnecessary words, and every sentence adds value.

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

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

Given the tool's simplicity (1 parameter, output schema exists), the description is complete. It explains what the tool does, how to use it, and what to expect (matching packs with details). The output schema covers return structure, so no further detail is needed.

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 is fully covered with 100% description for the single 'query' parameter. The description adds extra meaning by explaining that the query searches across names, descriptions, and tools, which the schema description ('Search query') does not specify.

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 searches packs by keyword across names, descriptions, and tools, with specific examples ('weather', 'translate'). This distinguishes it from siblings like 'list_packs' (which likely lists all packs) and 'get_pack_tools' (which retrieves tools for a specific pack).

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 usage context: 'Use to find specific capabilities.' While it does not explicitly exclude alternatives or state when not to use, the context is clear enough for an agent to understand it is for keyword-based search rather than browsing or 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?

Annotations already provide safety traits (readOnly, idempotent). Description adds significant behavioral context: embedding model (BGE-base-en), chunking strategy (500-char overlapping windows), similarity metric (cosine), cap with truncation flag, and offset for quote verification. No contradiction with annotations.

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

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

Every sentence earns its place. Core purpose front-loaded, followed by usage context, pairing info, and technical details. No fluff; structured logically from general to specific. Appropriately sized for a tool with moderate complexity.

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

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

Despite no output schema, description explains return format (top-N passages with offsets and similarity scores) and mentions truncation flag. Covers all essential aspects for an agent to invoke and interpret results correctly. No gaps given the tool's simplicity (3 parameters, no nested objects).

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

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

Schema coverage is 100% with parameter descriptions. Description enriches with concrete examples (e.g., 'SEC 10-K body' for text, 'supply-chain risk' for query) and clarifies limit range (1-20, default 5). Adds value beyond schema without overexplaining.

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 semantic search inside a fetched record with specific verb+resource ('semantic search INSIDE a fetched record') and distinguishes from sibling tools like ask_pipeworx_grounded by specifying when to use ('Use when the record is too big to cram into the prompt'). Purpose is clear and distinct.

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

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

Explicit when-to-use guidance: 'Use when the record is too big to cram into the prompt'. Pairs with ask_pipeworx_grounded for a two-step process. Also mentions constraints (200K char cap, truncation flag) helping agent decide appropriateness.

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

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

The description adds behavioral context beyond annotations: requires OAuth account, SMS cap of 10/day, webhook auto-disable after 10 failures, and that the feed is always on. It does not 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 front-loaded with purpose and is dense with information. It efficiently covers requirements, types, and delivery without redundancy, though it is lengthy.

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 states the return value (subscription id). It covers all relevant aspects: types, delivery options, limitations, and account requirements, making the tool fully understandable.

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

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

Schema coverage is 100%, but the description adds extensive examples and constraints for each type and delivery channel, clarifying parameter structures and restrictions (e.g., SMS must match verified phone, webhook signing details).

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

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

The description clearly states the tool creates a 'proactive monitoring subscription to a live-data event stream' and returns a subscription id. It distinguishes itself from sibling tools like list_subscriptions and unsubscribe by focusing on creation and specifying supported event types.

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

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

The description explains when to use (proactive monitoring with live-data streams), prerequisites (Pipeworx OAuth account), and limitations (anonymous/BYO cannot persist). It provides type-specific examples but does not explicitly contrast with pull-based tools like recent_alerts.

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 that it returns exact tool+argument shapes from the live catalog and is the onboarding entry point, giving richer 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 common trigger phrases and is well-structured. While slightly verbose, every sentence adds meaningful information without redundancy.

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

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

Despite lacking an output schema, the description fully explains the return format ('category-bucketed example questions with exact tool+argument shape'). It covers the tool's role as an onboarding entry point and references the live tool catalog, making it contextually complete for its purpose.

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

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

Schema coverage is 100% with a clear description of the optional 'topic' parameter. The description adds value by specifying example topic values ('finance', 'pharma') and explaining that omitting it returns a cross-category spread, going 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 explicitly states the tool's purpose: 'Returns category-bucketed example questions for Pipeworx.' It lists specific categories and identifies itself as 'the onboarding entry point,' clearly distinguishing it from siblings by its role.

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 advises 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' It also explains when to pass the optional 'topic' parameter. No explicit when-not-to-use, but strong guidance is provided.

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 it's a write operation but not destructive. The description adds valuable context: the row is deactivated (not deleted) and historical events remain available via recent_alerts, which is beyond what annotations provide.

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

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

The description is extremely concise: two sentences that efficiently convey purpose and behavioral details 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 simple one-parameter tool with no output schema, the description covers all necessary information: action, ownership constraint, and the effect (deactivation vs deletion) including where historical data persists.

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

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

Schema coverage is 100% with a description for the 'id' parameter. The description adds context that the id is returned by 'subscribe', which helps the agent understand the source of the 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 action 'Cancel a subscription by id' and distinguishes from siblings like 'subscribe' and 'list_subscriptions'. It specifies ownership enforcement, making the purpose unambiguous.

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

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

The description indicates when to use the tool: to cancel your own subscriptions. It implies that the user should have the subscription id and ownership, but does not explicitly state when not to use or provide alternatives, though context makes it 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=true, idempotentHint=true, and destructiveHint=false. The description adds behavioral details beyond annotations: it lists the return values (verdict, extracted structured form, actual value with citation, percent delta) and the data sources (SEC EDGAR + XBRL). No contradictions. The description enriches understanding of what the tool does and produces.

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 about 4 sentences, well-structured: starts with user intents, then purpose, then usage, then domain and output. Every sentence adds value. Slightly long but not wasteful; a model of clarity and efficiency.

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

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

No output schema is provided, but the description details the output format (verdict, extracted form, actual value, citation, percent delta). Given the tool's simplicity (single param, no nested objects) and rich annotations, the description fully informs an AI agent about what to expect. No gaps.

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

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

Schema coverage is 100% for the single parameter 'claim', with a good inline description. The overall description adds extra context: examples of claim formats, the domain scope, and mention of natural-language processing. Baseline is 3; the extra context justifies a 4.

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

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

The description starts with multiple natural-language user intents ('Is it true that…', 'fact check', etc.), then clearly defines the tool as 'natural-language claim verification against authoritative sources'. It specifies the domain (company-financial claims for US public companies) and distinguishes it from sibling tools by noting it replaces multiple sequential calls. This is specific, verb-driven, and unambiguous.

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

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

The description explicitly states 'Use whenever the agent needs to check whether something a user said is factually correct.' It also provides domain constraints ('v1 supports company-financial claims for public US companies') and explains how it improves efficiency over multiple steps. This gives clear when-to-use guidance.

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