Hongkong Procurement

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds useful context: default model is free, Anthropic requires own key and direct payment, and return structure includes per-model {score, confidence, signals, raw_response} plus combined view. No contradictions.

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

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

The description is a single, well-structured paragraph of four sentences. Every sentence serves a purpose: core action, default model, optional model with key, returns, and use cases. No fluff or repetition.

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

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

Given 4 parameters, no output schema, and low complexity, the description covers the essential: core functionality, return format, use cases, and model details. Missing explicit guidance on score interpretation but overall sufficient for an AI agent to select and invoke correctly.

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

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

Schema description coverage is 100%, but the description adds value by explaining default model choice for 'models', the key requirement for Anthropic, and the context parameter's purpose for disambiguation. This augments the schema's minimal 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 action ('Probe one or more LLMs'), the resource (business/brand/product/topic), and the output (visibility score 0-100). It differentiates from siblings by focusing on LLM knowledge scoring, distinct from other research tools like 'resolve_entity' or 'entity_profile'.

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

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

Explicit use cases are provided: AI-marketing audits, pre-launch brand checks, competitive monitoring. However, it does not mention when not to use this tool or provide direct comparisons to sibling tools, so it lacks explicit exclusions.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds behavioral context: 'one fast call, works on every tier', 'returns stable pipeworx:// citation URIs', 'fills arguments'. No contradictions.

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

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

Description is front-loaded with key instruction ('PREFER OVER WEB SEARCH'), then lists many examples and usage guidance. It is comprehensive but not overly verbose, though could be slightly trimmed.

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

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

For a tool backed by 4,774 tools across 1242 sources, the description covers core functionality, usage guidance, and sibling differentiation. It lacks return format details but is sufficient given no output schema.

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

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

Schema has 6 parameters, all aliases for 'question', with 100% coverage. Description reiterates aliases but adds no new semantics beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states the tool routes questions to a large set of verified sources and returns structured answers with citations. It distinguishes itself from siblings by saying 'PREFER OVER WEB SEARCH' and lists many specific query 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?

Explicitly says when to use this tool (start here for most factual questions) and when not to (use ask_pipeworx_grounded for hallucination-resistant answers, deep_research for broad questions). Also gives concrete examples and triggers like 'what is', 'look up'.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds significant context: one extra LLM call, returns specific structure with evidence quote, confidence, refusal reasons, and refusal cases. 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 somewhat long but every sentence adds value. Front-loads purpose and key differentiator. Could be slightly more concise, but structure is clear with bullet-like details on return format and refusal reasons.

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 (high-stakes, refusal mechanism, many sibling tools), the description covers purpose, usage, behavior, output format, and cost. No output schema exists, but return format is described completely. Contextually complete for an AI agent to select and invoke correctly.

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

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

Schema description coverage is 100%, so description does not need to add much. It mentions 'question' as alias but schema already describes aliases. Baseline 3 is appropriate as description adds minimal semantic value beyond schema.

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

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

Description clearly states it is a 'hallucination-resistant answer mode for high-stakes reads' and explains the process: same routing as ask_pipeworx, picks tool, fetches data, then extracts answer using only tool result. Distinct from sibling ask_pipeworx by adding extraction with refusal mechanism.

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

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

Explicitly says when to use: 'whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts' with examples (financial verdicts, legal claims, medical lookups, public statements). Also contrasts with ask_pipeworx for casual lookups, stating it costs one extra LLM call.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and non-destructive. The description adds extensive behavioral context: resolver contract (confidence levels, match scores, alternatives), parent event extraction, news fallback fields, safety short-circuits, wide-spread handling, and resolution-rule risk. This far exceeds the annotations and provides critical behavior details.

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 clear sections (RESPONSE SHAPES, RESOLVER CONTRACT, etc.). The first sentence conveys the core purpose. While verbose, every section adds unique value for a complex tool. It earns a 4 for being appropriately detailed without unnecessary redundancy.

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

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

Given the tool's complexity (3 parameters, no output schema, diverse behavior), the description covers all essential aspects: input format, resolution logic, parent event handling, news fallbacks, safety mechanisms, and risk disclosures. It is fully self-contained and leaves no gaps for agent understanding.

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 tool description adds value by reinforcing parameter usage with examples (e.g., market slug, URL, or question text) and explaining depth and include_raw in context. This provides additional clarity beyond the schema.

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

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

The description clearly states the tool's purpose: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies the resource (Polymarket bet) and action (research), and distinguishes from sibling tools by providing specific use cases and fan-out examples.

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

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

The description explicitly says 'Use for...' with example queries ('should I bet on X', 'what does the data say about Y', 'is there edge in Z'). While it doesn't directly mention when not to use or alternatives, the context is clear and sufficient for appropriate tool selection.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds substantial behavioral context: data sources (SEC EDGAR/XBRL for companies, FAERS/FDA/clinical trials for drugs), handling of off-calendar fiscal years, sorting by primary metric, and inclusion of citation URIs. No contradictions with annotations.

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

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

The description is a single paragraph with front-loaded examples. Every sentence adds value: trigger phrases, core functionality, data details per type, sorting behavior, output format, and efficiency claim. No redundant or filler content.

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

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

Despite no output schema, the description adequately explains return format (paired data + citation URIs). It covers entity-specific data sources, sorting, and off-calendar handling. Minor gaps (e.g., error handling, rate limits) don't detract significantly given the tool's simplicity and strong annotations.

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

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

Schema coverage is 100% (both parameters documented). The description adds meaning beyond the schema: for 'type', it specifies exactly what data is pulled for 'company' (10-K financials) vs 'drug' (adverse events, approvals, trials). For 'values', it clarifies input formats (tickers/CIKs for companies, names for drugs) which is helpful beyond the schema's generic array 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 begins with example queries (e.g., 'Compare X and Y', 'rank these companies') and clearly states the tool performs side-by-side comparison of 2-5 companies or drugs in one parallel call. It distinguishes itself from sequential single-pack lookups, providing a specific verb-resource pair with clear scope.

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 'ALWAYS PREFER over sequential single-pack lookups when comparing entities', giving direct when-to-use guidance. It also lists trigger phrases ('X vs Y', 'which is bigger') that help the agent recognize appropriate contexts.

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

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

Adds rich behavioral context beyond annotations: account requirement, paid plan for 'thorough' depth, parallel decomposition across 4,774 tools, output format with evidence/confidence/source/citation/gaps, timing estimate (15-60s), and limitation that it returns empty gaps for unstructured topics. 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?

Well-structured with front-loaded prerequisite and alternative. Each sentence serves a purpose (usage, mechanism, output, limitations). Slightly long but justified given complexity. Could be trimmed slightly 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?

Completely describes the tool's behavior, prerequisites, use cases, output format, and limitations. No output schema exists, but description covers return values. Given tool complexity (2 params, no output schema, good annotations), the description leaves no gaps for an agent to choose and invoke correctly.

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

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

Description enriches both parameters: for 'depth' explains numeric semantics (quick=3, standard=5, thorough=8) and plan restriction; for 'question' adds context that broad/multi-part questions are acceptable and decomposition is a feature. Schema coverage is 100%, so baseline is 3, but description adds significant 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 performs grounded multi-source research across Pipeworx's structured data sources. Distinguishes from sibling ask_pipeworx by specifying use case (broad/multi-part vs single lookup) and network scope (structured vs open-web/news). Uses specific verb 'research' and resource '1242 structured data sources'.

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

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

Explicitly says when to use ('Best for broad/multi-part questions over structured data') and when not to ('For a single lookup use ask_pipeworx', 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx'). Also provides prerequisite: account required, and alternative if not signed in.

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 valuable behavioral context: it returns the top-N most relevant tools with full input schemas, eliminating the need for a second schema lookup. This enhances the agent's understanding of the tool's behavior 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 a single, well-structured paragraph that front-loads the purpose and usage, then elaborates on behavior and output. It avoids unnecessary words but is dense with information. Minor improvement could be breaking into bullet points, but it remains effective.

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

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

Given no output schema, the description adequately explains the return value: top-N tools with names, descriptions, and full input schemas. It covers the tool's primary function, usage context, and output format completely. No gaps remain.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by providing examples of query usage (e.g., 'analyze housing market trends') and noting that multiple aliases (task, q, description, search) are accepted, which helps the agent understand flexibility in parameter naming.

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

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

The description clearly identifies the tool as a discovery mechanism for finding other tools by describing the data or task. It uses the specific verb 'discover' and distinguishes from sibling tools, which are individual data sources or actions, by positioning this as a meta-tool for exploration.

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

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

The description explicitly states when to use this tool: 'Call this FIRST when you have many tools available and want to see the option set.' It also provides a list of example domains (SEC filings, FDA drugs, etc.) and encourages using it for browsing and searching. It does not explicitly state when not to use it, but the guidance is clear enough.

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

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

Discloses fan-out behavior, specific data sources, soft-fail for patents, return fields, and parallel execution, adding rich context beyond readOnlyHint and idempotentHint annotations.

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

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

Densely packed with useful information, front-loaded with examples, but slightly verbose; every sentence adds value, so still effective.

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

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

Despite no output schema, the description thoroughly explains return fields, limitations (names, patents), and behavior, making the tool's usage and output predictable.

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 examples, explains that type is only 'company', clarifies value accepts ticker or CIK, and warns against names, significantly enhancing understanding.

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

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

The description clearly states it creates a full cross-source profile of a US public company in one parallel call, with examples and a list of data sources, distinguishing it from chaining 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?

Explicitly states to prefer this over chaining single-pack lookups for holistic views, and instructs to use resolve_entity if only a name is available, providing clear usage context.

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

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

Annotations indicate destructiveHint=true and readOnlyHint=false. Description adds context about clearing sensitive data and that it deletes previously stored memory, which is consistent and informative.

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

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

Two concise sentences with clear action first. 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 destructive tool with no output schema, the description fully covers purpose, usage context, and relationship to siblings.

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 'key' described as 'Memory key to delete'. Description adds 'by key' but does not provide additional semantics 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 states 'Delete a previously stored memory by key' which specifies the verb, resource, and parameter. It distinguishes from sibling tools 'remember' and 'recall'.

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

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

Provides clear use cases: 'when context is stale, the task is done, or you want to clear sensitive data'. Mentions pairing with siblings but lacks explicit when-not-to-use or alternatives.

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

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

Annotations already indicate read-only, open-world, idempotent, non-destructive behavior. The description adds valuable behavioral context: it fetches the page, extracts title/description/key links, and outputs standard llms.txt markdown. This goes beyond annotations and fully discloses the tool's operation.

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

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

The description is concise with three sentences, each adding value: the main action, the process, and use cases. No redundant or vague statements. Information is front-loaded.

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

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

Given no output schema, the description explains the output format ('single text blob ready to drop at site-root/llms.txt'). Use cases are covered. It lacks error handling or edge-case details, but for a simple tool with high schema coverage and annotations, this is sufficient. Minor gap: no mention of what happens if the URL is unreachable.

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

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

Schema description coverage is 100%, so the baseline is 3. The description does not add extra parameter-specific information beyond the schema (e.g., default for max_links is given in schema). The description mentions 'any URL' and 'production-ready' but doesn't elaborate on parameters further.

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

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

The description clearly states the tool's purpose: generating a production-ready llms.txt file for any URL. It specifies the action (generate), the resource (llms.txt file), and the target (URL). It also distinguishes itself from sibling tools by focusing on this specific output format.

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 scenarios: getting a client's site indexed, drafting for own project, or auditing competitor visibility. It does not explicitly exclude any cases or mention alternatives, but the context is sufficient for an agent to decide when to use this tool.

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

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

Annotations indicate readOnly, idempotent, openWorld, non-destructive. The description adds that queries are case-insensitive substring matches across subject, contractor, tender reference, and department. It discloses the fields returned (tender reference, subject, contractor, amount in HK$, award date). 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 mostly concise with two sentences. The first sentence clearly states purpose and data source. The second sentence covers parameters and usage examples. While the second sentence is somewhat long, it remains efficient and front-loaded.

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

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

Given no output schema, the description lists all returned fields. It explains the optional query vs. listing recent awards. It covers the dataset source and provides usage examples. It does not mention result ordering or error handling, but these are not critical for a simple search tool with two parameters.

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. The description adds value by specifying that the query parameter performs a 'case-insensitive substring to filter awards by subject/particulars, contractor name, tender reference, or department' and provides concrete examples. It also notes default limit of 25 and max of 100, adding context beyond the schema.

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

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

The description explicitly states 'Search recently AWARDED Hong Kong government procurement contracts from the Government Logistics Department (GLD)', specifying the verb (search), resource (awarded contracts), and data source. It distinguishes from sibling tools (e.g., ask_pipeworx, deep_research) by being domain-specific to HK procurement.

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

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

The description provides clear guidance: 'Pass an optional query to filter...; omit query to list the most recent awards'. It also gives example questions like 'who won the HK water treatment contract'. It implies the tool is for awarded contracts only, but does not explicitly exclude non-awarded stages.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. Description adds context about returning fields and default active-only scope, which is complementary and non-contradictory.

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

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

Two concise, front-loaded sentences with no filler. Every sentence serves a purpose.

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

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

Given low complexity, annotations, and only one optional parameter, the description fully covers purpose, usage, and return fields without needing an output schema.

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

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

Schema already has 100% coverage for the single boolean parameter. Description adds minimal extra meaning beyond 'active' implying default filter.

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

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

Clearly states the tool lists the caller's active subscriptions and enumerates return fields. Distinguishes from siblings like subscribe and unsubscribe.

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

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

Explicitly advises using this to review monitoring before adding more subscriptions or to find an id for cancellation.

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

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

The description discloses rate limits (5 per identifier per day), cost (free, no quota impact), and how feedback is processed (daily digests, influences roadmap). No contradictions with annotations, and it provides context beyond annotations.

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

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

The description is concise (about 70 words) and front-loaded with purpose. Each sentence earns its place: purpose, usage, constraints, and additional notes. No fluff.

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

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

Given no output schema, the description adequately explains the feedback lifecycle and what to expect (daily digests, roadmap influence). It covers all necessary aspects for an agent to use this tool correctly.

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

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

Schema coverage is 100%. The description adds value by explaining each enum value for 'type' and describing the 'context' and 'message' fields with practical guidance (be specific, 1-2 sentences).

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 sends feedback to the Pipeworx team, specifically for reporting bugs, missing features, data gaps, or praise. It distinguishes itself from sibling tools by being the dedicated feedback channel.

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

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

The description explicitly lists the feedback types (bug, feature, data_gap, praise) and instructs the agent not to paste the end-user prompt. It also mentions rate limits and that it's free, 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 declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds valuable behavioral context: data source ('CF analytics-engine'), privacy ('no PII'), data structure ('pack, tool, count'), and caching behavior ('Cached 5min-1h'). This goes beyond annotations without contradiction.

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

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

The description is moderately concise: one sentence for purpose, followed by bulleted use cases. It front-loads the main functionality. However, the three use cases could be slightly condensed without losing value. 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?

For a simple read-only tool with one parameter, the description covers purpose, use cases, data privacy, and caching. The absence of an output schema is compensated by explaining the return structure (packs, tools, counts). It could note the output format more explicitly, but it's fairly complete given the tool's simplicity.

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

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

The input schema has 100% coverage with a single parameter ('window') fully described. The description repeats the same guidance as the schema ('24h default, shorter windows surface hot data, longer windows steady-state'). No additional parameter meaning is added beyond the schema.

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

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

The description clearly states the tool returns top tools, top packs, and total call volume over specified windows. This distinguishes it from sibling tools like 'discover_tools' or 'ask_pipeworx' by focusing on trending data derived from agent calls.

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

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

The description lists three explicit use cases: discovering hot data sources, confirming popular tools, and checking alignment with agent needs. While it does not specify when not to use the tool, the context provided is sufficient for typical use. No alternative tools are mentioned, but the use cases imply when this tool is appropriate.

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 the tool is read-only, open-world, idempotent, and non-destructive. The description adds substantial behavioral context: it explains internal checks (semantic anchor, partition filter, fill check), details of the return objects (opportunities, partition_check), and provides actionable logic like not trading when realizable_edge_pp ≤ 0. 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 thorough but somewhat lengthy. It is front-loaded with the purpose and each subsequent section adds necessary detail. While it could be slightly more concise, no information is redundant, and the structure (mode breakdown, internal checks, output description) is logical.

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 (opportunities array with fields, partition_check in event mode) and references related tools (polymarket_fill_risk). It covers all modes, edge cases (placeholder filter), and practical usage (fill check). The description leaves no gaps for an AI agent to misinterpret the tool's capabilities.

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

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

Both parameters have schema descriptions, but the tool description adds valuable nuance: examples of valid slugs/topics, explanation of what each mode does internally, and the difference between event and topic. This goes beyond the schema's basic descriptions, aiding correct invocation.

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 finds arbitrage opportunities using two specific methods (monotonicity violations and partition-sum checks). It clearly distinguishes the three operation modes (no args, event, topic) and provides enough detail to differentiate 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?

The description provides explicit guidance on when to use each mode: no args for a trending scan, event for a specific market, and topic for cross-event scanning. It also advises against trading when the realizable edge is non-positive. However, it does not explicitly exclude alternatives among sibling tools, though the context is clear.

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

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

The description discloses behavioral traits far beyond annotations, including the three response segments, detailed model explanations (e.g., lognormal barrier, GDELT ratio), caching at KV level for 1h, and diagnostics for empty segments. It also explains why Fed bets are excluded. No contradiction with annotations (readOnlyHint, idempotentHint).

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

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

The description is lengthy but every sentence earns its place given the tool's complexity (9 parameters, model families, diagnostics). It is front-loaded with the purpose and then details. Minor redundancy could be trimmed, but overall efficient.

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

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

Despite no output schema, the description fully covers what the tool returns: by_segment, fed_candidates, diagnostics. It explains edge calculations, Kelly fractions, and filtering logic. Given the high parameter count and complexity, it is remarkably complete.

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

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

Schema coverage is 100%, but the description adds crucial context: e.g., min_kelly as '0.005 = 0.5% of bankroll', slippage_pp explaining market depth, and min_partition_leg_kelly justifying its separate use. Each parameter's purpose and default values are explained 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 scans Polymarket markets to return opportunities where Pipeworx data disagrees with market price. It uses a specific verb-resource pair ('Scan top Polymarket markets and return opportunities') and distinguishes itself from sibling tools like polymarket_arbitrage and polymarket_edge_tracker by focusing on model-driven 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 is built for 'what should I bet on today' and details when to use knobs like min_liquidity and max_spread_pp. It implicitly differentiates from siblings but lacks explicit when-not-to-use instructions. However, the context signals (siblings) and the description's focus on edge discovery provide clear context.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds significant behavioral context: snapshot-based with 60-day TTL, cache-miss gaps, decay from daily closes (net of default slippage), and explanation of expired opportunities. 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 informative but lengthy with detailed output structure and limitations. It front-loads the core purpose but includes verbose definitions of response fields. Could be trimmed while retaining key 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?

Despite no output schema, the description thoroughly explains output fields (tracked, expired, snapshot_dates) with field meanings and limits. It covers potential gaps and assumptions (e.g., default slippage, snapshot TTL). Complete for a complex tool.

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

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

Schema coverage is 100% with descriptions for both parameters. The description adds context for default values (days=14, window='1wk') and limits (days max 30), going beyond schema. Minor inconsistency: description says 'max 30' while schema says 'clamp 2-30', but overall improves 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: providing edge persistence and decay telemetry from daily snapshots. It uses specific verbs and resources ('Edge persistence and decay telemetry') and distinguishes from siblings like polymarket_edges by focusing on historical persistence rather than current 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 implies usage for assessing edge longevity and decay, and contrasts fresh vs. old edges. However, it does not explicitly state when to use this tool over siblings like polymarket_edges or polymarket_arbitrage, nor does it provide alternative names.

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 readOnly, openWorld, idempotent, and non-destructive. The description adds behavioral details: walks the order-book ladder, computes slippage, returns verdict (clean|degraded|cannot_fill), and warns about forced directional risk in basket mode. No contradiction.

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

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

The description is dense but well-structured with clear mode sections and front-loaded purpose. Every sentence adds value, though length is justified by the tool's 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?

No output schema exists, but the description thoroughly lists all return fields for both modes, explains edge cases (thin legs, forced directional risk), and provides usage rationale. Complete for a complex tool.

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

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

Schema coverage is 100% with clear parameter descriptions. The tool description adds additional context, such as default side auto in basket mode and the meaning of size_usd per mode, enhancing understanding beyond the schema.

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

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

The description clearly states the tool's purpose as a 'Realizable-vs-theoretical edge check against live CLOB order-book depth', specifies two distinct modes (single-market and basket), and lists return fields. It distinguishes itself from sibling tools like polymarket_arbitrage by explicitly recommending its use before acting on signals from those tools.

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

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

The description explicitly instructs to use this tool before acting on polymarket_arbitrage signals or polymarket_edges trades above $500. It explains why (thin books, partial fill risks) and provides mode-specific requirements (requires market or event parameter).

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

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

Adds extensive details beyond annotations: explains compatibility_warning triggers, temporal alignment, skipped cross types, and clarifies that real spreads are rare. Annotations already mark as read-only and idempotent, no contradiction.

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

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

Quite verbose with detailed safety field explanations, but well-structured with headings (TWO MODES, RESPONSE, SAFETY FIELDS) and front-loaded purpose. Could be more concise.

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

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

Given no output schema, the description thoroughly explains return fields like compatibility_warning, temporal_alignment, and skipped counters. Covers edge cases and limitations, making it complete for agent invocation.

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

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

Schema covers all 3 parameters at 100%. Description adds context by listing the 10 topic shortcuts and explaining how explicit tickers override mapped sides, providing usage nuance beyond schema.

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

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

The description clearly states it's a 'cross-venue spread between Kalshi and Polymarket' and explains the dual modes (topic shortcuts vs explicit tickers), differentiating it from intra-venue tools like polymarket_arbitrage.

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

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

Explicitly describes when to use each mode and warns that most pre-mapped topics currently return a compatibility_warning (pre-mapped ≠ tradeable). Lacks explicit comparison to sibling tools but the unique purpose is clear.

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

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

Annotations already provide readOnlyHint, destructiveHint, idempotentHint. The description adds scoping information ('Scoped to your identifier') and clarifies behavior when key is omitted, which adds value beyond annotations.

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

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

Three sentences, front-loaded with the core action, no extraneous words. 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 only one optional parameter, no output schema, and full annotation coverage, the description adequately explains behavior, scope, and lifecycle pairing. 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% with description for 'key'. The description adds examples of typical keys (ticker, address, notes) and reiterates that omitting key lists all, enriching the semantic context beyond the schema.

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

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

The description uses a specific verb ('Retrieve') and resource ('value previously saved via remember'), distinguishes clearly from siblings by naming 'remember' and 'forget', and provides concrete examples like 'user's target ticker, an address, prior research notes'.

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

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

Explicitly states when to use: 'Use to look up context the agent stored earlier... without re-deriving it from scratch.' Provides context for usage and pairs with 'remember' and 'forget' for lifecycle management.

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 show readOnlyHint=true and idempotentHint=true. Description adds context: side effect of mark_read, mentions feed persistence and return structure, 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?

Front-loaded with core purpose in first sentence. Subsequent sentences add necessary detail without redundancy. 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?

No output schema, but description covers return fields (source, citation_uri, raw event payload) and feed behavior. Lacks explanation of pagination or limits, but sufficient for basic 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 coverage is 100%. Description adds meaning beyond schema by explaining the use of mark_read (flags events read for next call), giving an example for type, and specifying ISO timestamps for since.

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 pulls fired events from the subscription feed, listing specific fields returned (source, citation_uri, raw payload). It distinguishes from siblings by mentioning an alternative HTTP endpoint for scripts/dashboards.

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 filtering options (type, since, mark_read, unread_only) and notes polling suitability. Mentions alternative access method, but lacks explicit when-to-use vs. 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?

Beyond annotations (readOnly, openWorld, idempotent), the description reveals fan-out behavior, fallback logic (GDELT→GNews), soft-fail for USPTO, and return format (changes grouped by source with citation URIs).

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

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

The description is detailed but well-structured with examples. It front-loads common query patterns and uses parentheses for supplementary info. Slightly long due to complexity, but efficient for the tool's breadth.

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

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

Given the tool's complexity (3 params, no output schema), the description fully explains inputs, sources, failure modes, and return structure. No gaps remain 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 covers 100% with parameter descriptions. The description adds further context like examples of relative 'since' values and fallback behavior, going beyond the schema.

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

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

The description clearly states the tool's purpose: 'change feed for a company in the last N days/weeks/months in ONE parallel call.' It lists specific sources (SEC EDGAR, GDELT→GNews, USPTO) and differentiates from sibling tool 'entity_profile'.

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

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

Provides explicit when-to-use examples ('Whats new with X', 'latest on Y') and a clear when-not-to-use directive: 'Use entity_profile instead when you want the static profile'. This guides the agent effectively.

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

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

Annotations indicate idempotentHint=true, destructiveHint=false. The description adds key behavioral details: key-value scoped by identifier, 24-hour retention for anonymous, persistent for authenticated. No contradiction with annotations.

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

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

Three sentences, front-loaded with purpose then usage. Every sentence adds value: no fluff, no repetition of schema. Efficient and 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?

With no output schema and only two required parameters, the description is fully complete. It explains scope (by identifier), lifetime, and pairing with sibling tools. 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%, so description adds marginal value beyond parameter names. However, it provides usage examples (e.g., 'subject_property', 'target_ticker') that help illustrate parameter purpose, elevating it above baseline 3.

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

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

The description uses a specific verb 'Save' and resource 'data the agent will need to reuse later'. It clearly states the tool's purpose for cross-session/conversation storage, distinguishes from siblings by mentioning recall/forget, and gives concrete examples (ticker, address, preference).

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

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

Explicitly states when to use: 'when you discover something worth carrying forward'. Provides alternatives: 'Pair with recall to retrieve later, forget to delete.' Also explains persistence differences for authenticated vs anonymous sessions.

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

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

Annotations indicate read-only, idempotent, non-destructive. The description adds that each call cascades through multiple endpoints and replaces manual lookups, plus details the returned fields for each entity type (ticker, CIK, RxCUI, etc.) and citation URIs.

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

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

The description is compact at 4 sentences, front-loaded with query examples for immediate recognition, then presents key details in a structured bullet-like format. 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 no output schema, the description fully explains the return values for both types, including citation URIs and disambiguation. It covers the essential behavioral aspect (multiple internal lookups) without omissions.

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

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

Schema has 100% coverage with descriptions. The top-level description adds specific examples (e.g., 'AAPL', '0000320193') and clarifies that the value parameter accepts ticker, CIK, or name for company, and brand/generic for drug, going beyond the schema's generic phrasing.

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

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

The description clearly states the tool resolves a name to a canonical identifier, with specific examples like 'ticker for...' and 'CIK for...'. It distinguishes from siblings via the directive 'Use FIRST whenever you have a name but need an ID.'

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 to use this tool first when needing an ID from a name, and gives concrete query examples. However, it does not explicitly state when not to use or list alternative tools for other scenarios.

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

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

Annotations already declare readOnlyHint, idempotentHint, and nondestructive. The description adds that it probes multiple entities via ai_visibility_check, ranks results, and outputs score/confidence/signal density. This provides useful behavioral context beyond annotations.

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

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

The description is four sentences: core action, mechanism, use case, output format. It is front-loaded, concise, and every sentence adds value. No redundant or vague statements.

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

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

Given the moderate complexity (multiple entities, comparison, no output schema), the description sufficiently explains input treatment, probing mechanism, ranking, and output fields. Combined with rich annotations, an agent has enough to use the tool correctly.

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

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

All parameters have schema descriptions (100% coverage), so baseline is 3. The description adds semantic value by specifying that the first entity is treated as the 'subject' for narrative and the rest as competitors, which is not in the schema. It also clarifies the role of context for disambiguation.

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, ranks them, and surfaces recognition levels. It distinguishes from sibling tools like ai_visibility_check (single entity) and compare_entities (general comparison), providing a specific verb and resource.

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

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

The description provides a clear use case (competitive AI-marketing audits) and an example question. It implies when to use but does not explicitly state when not to use or list alternatives. However, the sibling context helps agents differentiate.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds value by noting that the first bundlephobia measurement on a new version can take 5-30 seconds, partial failures degrade gracefully with sources_failed listing timeouts, and the tool fans across multiple external services. This goes 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 a single dense paragraph of about 150 words. While it front-loads the core purpose ('Composite should I add this npm package to my project check in ONE call'), the lack of structure (e.g., bullet points, sections) makes it harder to parse quickly. It contains some redundancy (e.g., 'NPM ecosystem only in v1' repeated).

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

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

Given no output schema, the description thoroughly explains return values (summary block, per-advisory details, links, alternative versions). It covers edge cases like partial failures, timeouts, and ecosystem limitations. It also mentions version handling and the composite nature. It is complete enough for an agent to understand what to expect.

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

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

Schema coverage is 100% (2 parameters described), so baseline is 3. The description adds meaning beyond the schema: it clarifies that package accepts scoped names (e.g., '@types/node'), explains the version defaults to latest, and describes the composite nature of the call. It also details the return fields (summary block, advisory detail, links, alternatives), which compensates for the lack of an output 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 explicitly states the tool's purpose: a composite check for npm packages combining deps.dev (licenses, advisories, version history) and bundlephobia (bundle size, dependency count, ESM/tree-shaking). It distinguishes from sibling tools by specifying 'NPM ecosystem only in v1' and listing specific queries it answers, e.g., 'is X safe / popular / small' or 'what does adding lodash cost me'.

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 guidelines: use whenever an agent asks about npm package safety/popularity/size or cost. It also specifies when not to use: for PyPI/Maven/Cargo/Go ecosystems, it falls under 'deps.dev:version directly'. This offers explicit alternatives and context.

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

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

Annotations already provide readOnlyHint, idempotentHint, etc., and the description adds significant behavioral details: character offset return, embedding model (BGE-base-en), window size (500-char), cap (200K chars with truncation flag), and similarity measure (cosine). No contradictions.

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

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

Two well-structured sentences. First sentence front-loads purpose and key benefit (saves context). Second sentence adds technical details and alternatives. 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?

Fully captures tool's behavior for its complexity: explains input, output (passages with offsets and scores), use case, limitations (200K cap), embedding details, and pairing with sibling. No output schema 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?

Schema coverage is 100%, but the description enriches each parameter: 'text' is clarified as 'document text you already pulled'; 'query' given natural-language examples; 'limit' notes default of 5. Adds value beyond schema.

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

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

The description clearly states the tool performs 'Semantic search INSIDE a fetched record', using specific verb ('search') and resource ('fetched record'). It distinguishes from siblings by explicitly naming alternatives like 'ask_pipeworx_grounded'.

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

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

Provides explicit when-to-use guidance: 'Use when the record is too big to cram into the prompt'. Also explains pairing with 'ask_pipeworx_grounded' as an alternative workflow, giving clear context.

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

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

Annotations already indicate it's a non-destructive write operation (readOnlyHint=false, destructiveHint=false, idempotentHint=true). The description adds: requires OAuth, returns subscription id, delivery channel behaviors (feed always on, email/sms optional with rate limits and verification), webhook signing details, and auto-disable after 10 failures. 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: front-loaded with purpose and return, followed by requirements, types with examples, and delivery channels. It is somewhat verbose but organized. Could be slightly more concise, but it earns its length.

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

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

Given the complexity of subscription types and delivery options, the description covers all essential aspects: types, params, delivery, return value, prerequisites, and behavioral notes (rate limits, webhook signing, secret management). No output schema exists, so the description compensates adequately.

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

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

Schema coverage is 100%, but the description adds significant meaning: it gives examples for each type, explains constraints (e.g., sponsor or condition required for clinical_trial), and details delivery object sub-fields (email pattern, SMS verification, webhook restrictions). This goes well beyond the schema.

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

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

The description clearly states the verb 'Create' and the resource 'proactive monitoring subscription to a live-data event stream'. It distinguishes from sibling tools like list_subscriptions (list), unsubscribe (remove), and recent_alerts (retrieve events).

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 explains when to use the tool (to create a subscription) and specifies prerequisites (requires Pipeworx OAuth account). It provides detailed examples of subscription types and delivery options. However, it does not explicitly mention when not to use it or point to alternatives for one-off alerts, but the context is clear enough.

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

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

Annotations already mark it as readOnly, idempotent, non-destructive. The description adds behavioral context: it is the onboarding entry point, returns example questions drawn from a live catalog, and can be called with no arguments. No contradictions; adds value beyond annotations.

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

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

The description is well-structured starting with common user queries, then explaining output. It is slightly verbose but each sentence adds value. Could be trimmed slightly, but still effective.

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

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

Given no output schema, the description fully explains the output format (category-bucketed example questions with tool+argument shape). It covers the primary use case and mentions meta-tool learning, making it complete for its intended 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 coverage is 100% with the optional topic parameter described. The description adds useful context: lists focus areas and explains omission yields cross-category spread. This goes beyond the schema's generic description, though the schema alone was already clear.

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

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

The description clearly states the tool returns category-bucketed example questions for onboarding, using specific verbs like 'returns' and listing topics. It distinguishes itself as the entry point, which differentiates it from sibling tools like ask_pipeworx or discover_tools.

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

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

Explicitly tells when to use it: '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 that omitting topic gives full spread, and passing topic focuses results, providing actionable usage 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 convey idempotentHint=true and destructiveHint=false, but the description adds critical detail: 'The row is deactivated (not deleted) so its historical events stay available via recent_alerts.' This moves beyond the annotations and informs the agent of side effects.

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

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

Two sentences covering all essential aspects: action, constraint, and behavioral nuance. No redundant words, front-loaded with the core purpose.

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

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

Given the tool has only one parameter and no output schema, the description is fully complete. It explains ownership, deactivation, and the impact on historical data, leaving no ambiguity.

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

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

Schema description coverage is 100%, so the schema already documents the 'id' parameter fully. The description does not add meaningful information beyond what the schema provides, meeting the baseline for a high-coverage scenario.

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 'Cancel a subscription by id', providing a specific verb and resource. It clearly distinguishes itself from sibling tools like 'subscribe' and 'list_subscriptions' by adding ownership enforcement and deactivation behavior.

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 'Ownership is enforced — you can only cancel your own subscriptions', giving clear guidance on when to use the tool. It does not explicitly mention alternatives, but the context is sufficient for differentiation.

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

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

The description adds significant value beyond annotations: it details return types (verdict categories, structured form, actual value with pipeworx:// citation, percent delta) and explains that it replaces 4-6 sequential calls. Annotations already mark it as read-only, idempotent, and non-destructive, and the description aligns with these.

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

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

The description is informative but somewhat lengthy. It is well-structured: starts with example triggers, states purpose, lists capabilities, describes output, and notes efficiency. However, 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?

For a tool with one simple parameter, rich annotations, and no output schema, the description is comprehensive. It covers domain, usage context, return types, and efficiency benefits. No missing critical details for agent invocation.

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

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

The input schema has 100% description coverage for the single parameter 'claim'. The description adds additional context by specifying the domain (company-financial claims) and examples, enhancing the schema's expressiveness.

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

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

The description clearly identifies the tool as a natural-language claim verification tool, specifically for company-financial claims via SEC EDGAR + XBRL. It distinguishes from siblings by noting it replaces multiple sequential calls and provides concrete usage examples.

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

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

The description explicitly states when to use: 'whenever the agent needs to check whether something a user said is factually correct' and gives example queries. It implies limitations by specifying support for company-financial claims but does not explicitly state when not to use (e.g., non-financial claims).

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