Hongkong Procurement

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and no destructiveness. The description adds value by explaining the return structure (per-model {score, confidence, signals, raw_response} + combined view) and cost implications for Anthropic. It does not contradict annotations and provides behavioral context beyond what annotations convey.

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

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

Two sentences: the first covers the main action and output, the second adds details and use cases. Every phrase is necessary; no fluff. The description is front-loaded with the most critical 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 adequately explains return values. All 4 parameters are documented in the schema and the description adds practical context. For a read-only probe tool with clear annotations, this description covers all necessary aspects an agent needs to invoke it correctly.

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

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

Schema coverage is 100% with descriptions for all 4 parameters. The description adds meaning by explaining the default model for workers-ai, how _apiKey is passed through, and that context helps disambiguate. This goes beyond the schema's 'description' fields.

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 probes LLMs for visibility of an entity and returns a score. It distinguishes from sibling tools by specifying 'score visibility (0-100) per model' and provides use cases like AI-marketing audits and competitive monitoring, differentiating it from general search or entity profile 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 recommends use cases (AI-marketing audits, pre-launch brand checks, competitive monitoring) and explains the default model vs. paid Anthropic option. It does not explicitly contrast with sibling tools like compare_entities or scan_competitor_ai_presence, but the guidance is clear enough for an agent to decide 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 declare readOnlyHint, idempotentHint, and destructiveHint=false. The description adds valuable behavior beyond annotations: it routes to a large tool ecosystem, fills arguments, and returns pipeworx:// citations. This gives context without contradicting annotations.

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

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

The description is longer than typical but front-loaded with the critical 'PREFER OVER WEB SEARCH' directive and structured with examples and alternatives. Some redundancy (e.g., 'works on every tier, one fast call') could be trimmed, but the length is justified by the tool's broad applicability.

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

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

For a complex meta-tool with no output schema, the description covers all essential context: what it does, when to use it, examples, alternatives, and return format (structured answer with citations). It is fully complete for the decision-making and invocation needs of an agent.

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

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

Schema coverage is 100% with detailed descriptions and alias list. The description supplements this by providing concrete example questions and mentioning that the tool 'fills arguments', which adds practical meaning to the 'question' 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 routes questions to 5,558 tools and returns structured answers with citation URIs. It explicitly distinguishes itself from web search and from sibling tools like ask_pipeworx_grounded and deep_research, making its purpose unambiguous.

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

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

The description provides explicit when-to-use guidance: 'PREFER OVER WEB SEARCH' and 'START HERE', and also specifies when to step up to ask_pipeworx_grounded or deep_research. It even covers breaking news routing, making alternative selection crystal 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?

Beyond the annotations (readOnly, openWorld, idempotent), the description discloses the experimental nature: candidate routing improvements may be enabled live, no candidate is currently active so it matches ask_pipeworx exactly, and it is a full working router rather than a fallback. This adds meaningful lifecycle context.

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

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

Three dense sentences, each serving a distinct purpose: identity/beta status, current state, and usage instructions. Front-loaded with the key information and no filler.

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

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

Given the beta nature and no output schema, the description fully explains what the tool is, its relationship to ask_pipeworx, current behavior, and response shape. It is self-contained and sufficient for an agent to invoke it correctly.

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

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

The input schema already documents all 6 parameters with 100% coverage and alias descriptions. The description adds only that the tool shares the same arguments as ask_pipeworx, which is useful but does not substantially enhance understanding of the question parameter 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 identifies this as a beta version of ask_pipeworx, an identical universal router with the same 5,558 tools, arguments, and response shape. It distinguishes itself from the stable ask_pipeworx and clarifies it is a full working router, not a fallback.

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 instructs to use it exactly like ask_pipeworx when wanting the newest routing, and notes results are compared against the stable router to decide merges. This provides clear when-to-use context and names the primary alternative (ask_pipeworx).

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive. The description adds substantial behavioral context beyond annotations: exact failure refusal reasons (not_in_source, no_tool_match, tool_error, data_truncated, llm_error), the use of verbatim quotes as evidence, and the cost of an extra LLM call. 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 every sentence contributes: core purpose, routing mechanism, success/refusal return shapes, use cases, and cost comparison. The structure front-loads the key differentiator ('Hallucination-resistant answer mode') and then logically expands, making it easy for an agent to scan and extract the essential guidance.

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

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

Given the tool's complexity (routing, extraction, safety-critical use), the description fully addresses what the agent needs: return shape on success, refusal reasons, when to use it, and trade-offs vs alternative. No output schema is present, so the description appropriately explains return values. It is complete and self-contained.

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

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

Input schema covers all parameters with 100% description coverage (each alias explicitly described as 'Alias for question' and the main parameter described as natural language). The description does not add parameter-specific semantics but the schema already provides full meaning, so the baseline of 3 applies. The mention of 'fills arguments' hints at the tool auto-populating parameters, a minor addition.

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 this as a 'hallucination-resistant answer mode for high-stakes reads' and explicitly differentiates it from sibling 'ask_pipeworx' by emphasizing extraction only from tool results and the explicit refusal behavior. It states the exact action (EXTRACTS the answer) and resources (routing across 5,558 tools/1461 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?

Provides explicit when-to-use guidance: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts.' It also contrasts with the sibling tool: 'Costs one extra LLM call vs ask_pipeworx — prefer ask_pipeworx for casual lookups.' This gives clear direction on choosing between alternatives.

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

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

Annotations already declare read-only, open-world, and idempotent behavior. The description adds extensive behavioral details: resolution and classification process, fan-out to data sources, safety mechanisms (short-circuit on low confidence, skip for closed markets), resolution-rule risk parsing, and response shapes. 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-organized with section headers (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, etc.) and front-loaded with the main purpose. Every sentence adds value given the tool's complexity, though a slightly more streamlined version could improve readability.

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

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

No output schema exists, so the description must cover return values, which it does thoroughly: result.market, result.analysis, result.evidence, resolver contract, parent event extractor, news fields, and safety conditions. It also explains edge cases (low confidence, closed markets, wide spreads, cancellation rules) and blocking behaviors, making it complete 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 coverage is 100%, so baseline is 3. The description adds meaningful context beyond schema: clarifies that 'market' accepts slug, URL, or question text; explains 'depth' enum (quick vs thorough); and details 'include_raw' behavior (summarized vs full payloads). This additional guidance justifies a score above baseline.

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

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

The description clearly states the tool's purpose: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies input types (slug, URL, question text) and provides numerous fan-out examples, classifiers, and response shapes. The tool's unique function is evident, and it distinguishes itself from sibling tools by focusing on comprehensive bet research.

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

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

The description explicitly lists use cases: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It also discusses edge cases like low-confidence matches and closed markets, but does not explicitly state when not to use the tool 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 mark it read-only, open-world, idempotent, and non-destructive. The description adds value beyond annotations by detailing data sources (SEC XBRL for companies, FAERS for drugs), handling of off-calendar fiscal years, sorting by primary metric, and return of citation URIs. 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 front-loaded with trigger phrases and every sentence adds value. While slightly lengthy, it remains focused and efficient 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?

With only 2 parameters and no output schema, the description covers return format (paired data + citation URIs), sorting behavior, and edge cases (off-calendar fiscal years). Provides sufficient context for correct 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 type (enum) and values (array constraints with examples). The description adds meaning beyond the schema by explaining what each type value entails (e.g., company pulls 10-K data) and how to format values (tickers/CIKs vs drug names), enhancing usability.

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

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

The description uses specific trigger phrases (e.g., "compare X and Y", "X vs Y") and states it does side-by-side comparison of 2-5 companies or drugs. It clearly distinguishes from sibling tools like entity_profile (likely single-entity) and deep_research (broader 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?

Explicitly says "ALWAYS PREFER over sequential single-pack lookups when comparing entities," giving clear when-to-use advice. However, it does not explicitly state when not to use or mention alternatives, though sibling context implies them.

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

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

Annotations already tag it as read-only and idempotent, but the description adds critical behavioral traits beyond that: parallel decomposition across 5,558 tools, gaps[] for unanswered facets (never invented), contradictions[] for standard/thorough, resolvable citation_uri, semantic excerpting, and timing. 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 long but dense and well-structured, front-loading the critical account requirement and fallback in the first sentence. Every sentence adds distinct value, though some repetition (e.g., multiple mentions of gaps/contradictions) could be tightened.

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

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

For a complex tool with no output schema, the description fully covers inputs, depth semantics, output structure (findings packet with verbatim evidence, confidence, source, fetched_at), limitations (gaps for non-catalog topics), and runtime expectations. It is complete enough for an agent to use 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 both params 100%, so baseline is 3. The description adds meaningful context: explains the depth enum values in terms of facets and hops, notes 'thorough' requires a paid plan, and gives example questions. This goes 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 states a specific verb+resource: 'Grounded multi-source research across Pipeworx's 1461 STRUCTURED data sources' in one call. It explicitly distinguishes from sibling ask_pipeworx by noting it is NOT open-web search and is best for broad/multi-part questions.

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 ('Best for broad/multi-part questions over structured data') and when-not-to-use ('For a single lookup use ask_pipeworx', 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx'). Also gives account-sign-in fallback instructions 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, destructiveHint=false, idempotentHint=true. The description adds valuable behavioral context: it returns 'top-N most relevant tools with names, descriptions, and full input schemas (with curated examples) — each result is ready to call directly, no second schema lookup needed.' 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 paragraph of 4-5 sentences, front-loading the purpose and then providing when-to-use, examples, and return behavior. Every sentence is informative and no words are wasted.

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 fully explains the return format: tool names, descriptions, and full input schemas with examples. It also notes that results are ready to call directly. This is complete for the tool's purpose of discovery.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by clarifying that the query parameter accepts multiple aliases (q, task, search, description) and by providing natural language examples. This goes slightly beyond the schema descriptions.

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

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

The description clearly states the tool's purpose: 'Find tools by describing the data or task.' It lists many specific domains and explicitly distinguishes from siblings by saying 'Call this FIRST when you have many tools available and want to see the option set.' This provides a specific verb and resource, and differentiates it from 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 explicitly states when to use: 'Use when you need to browse, search, look up, or discover what tools exist for...' and advises 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This gives clear context 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?

Annotations already declare readOnlyHint=true, openWorldHint=true, etc. The description adds rich behavioral context: it fans out across multiple sources, details return fields, and notes the USPTO patents API sunset and soft-fail behavior. 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 dense paragraph that front-loads query examples. It is concise given the amount of information, though the listing of return fields makes it slightly longer than minimal. 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 tool's complexity (multiple sources, specific data fields, sunset note) and lack of output schema, the description provides complete information about what the tool returns and its limitations. No obvious 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 descriptions for both parameters. The description adds extra context (ticker vs. CIK, no names, resolve_entity reference), but since the schema already fully describes parameters, the added value is moderate.

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

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

The description uses specific verb+resource ('full cross-source profile of a US public company'), lists example queries, and distinguishes from chaining single-pack lookups. It clearly states what the tool does and differentiates it from siblings.

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

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

Explicitly states when to prefer this tool over alternatives ('ALWAYS PREFER over chaining...'), and what inputs are not supported (names) with a pointer to resolve_entity. Provides 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 already indicate destructive and idempotent behavior; description adds context about use cases but doesn't detail idempotency. 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?

Two concise sentences with front-loaded action and no unnecessary words.

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

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

For a simple delete tool with one parameter and no output schema, the description fully covers purpose, usage, and relationships.

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 describes the single parameter 'key' with 100% coverage. Description adds no extra meaning beyond 'memory key to delete'.

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 'Delete a previously stored memory by key' with specific verb and resource. Distinguishes from siblings '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?

Explicitly provides when-to-use scenarios (stale context, task done, clear sensitive data) and mentions pairing with related 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, destructiveHint=false. The description adds behavioral context: it fetches the page (network call), extracts specific content, and outputs markdown. No contradictions.

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

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

Three sentences, front-loaded with purpose, no redundant 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 low complexity (2 params, no output schema), the description covers the purpose, process, output, and use cases adequately. No missing critical information.

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 parameters (url, max_links) are already documented. The description does not add extra meaning beyond restating the purpose. 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 it generates an llms.txt file for a given URL, specifying the actions (fetch, extract, emit) and the standard markdown format. It distinguishes itself from sibling tools by focusing on a specific AI indexing use case.

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 (client sites, own projects, competitor auditing), but does not mention when not to use or alternative tools. Sibling names suggest related tools, but no direct comparison.

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 annotations already declare readOnly, idempotent, and non-destructive behavior. The description adds valuable behavioral details: case-insensitive substring filtering across multiple fields, and the specific output fields returned. 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?

Three sentences, front-loaded with the main purpose, then output details, then usage guidance. Every sentence is informative, no redundancy.

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

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

The description covers data source, returned fields, filtering behavior, and provides examples. For a simple lookup tool with no output schema, this is comprehensive. One minor gap: no mention of data freshness beyond 'recently', but the award date field mitigates this.

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 meaning by specifying which fields are searched by the query parameter (subject, contractor, tender reference, department). This goes beyond the schema's 'substring filter' phrasing. Default and max for limit are already in 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 it searches recently awarded Hong Kong government procurement contracts from the GLD dataset, specifies the returned fields, and gives usage examples. The verb 'search' and resource 'awards' are clear, and no sibling tool competes directly, so distinction is implicit.

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

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

The description clearly indicates when to use with or without a query, and provides example questions. It does not explicitly state when not to use or list alternatives, but given no similar tools, the guidance is sufficient.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds return field names and the include_inactive parameter, but does not disclose additional behavioral traits beyond what annotations cover.

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 wasted words. The purpose and key details are front-loaded, making it highly 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?

Given the tool's simplicity (one optional parameter, no nested objects, rich annotations), the description is complete except for not specifying the output schema (which is absent). It provides enough context for an agent to use the tool correctly.

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

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

Schema coverage is 100% with a clear description for the only parameter. The description adds minimal extra meaning, merely implying the default by mentioning 'active subscriptions.'

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

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

The description clearly states the tool lists active subscriptions and specifies the returned fields (id, type, params, etc.). It distinguishes from sibling tools like 'subscribe' and 'unsubscribe' by focusing on listing.

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: review subscriptions before adding more or find an id to cancel. This guides the agent on when to use the tool, but does not explicitly state 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?

With all annotations false, the description carries the full burden. It discloses the claim_token flow (filing without an account returns a token, which can be used later to read status), rate limiting (5 per identifier per day), that it is free and doesn't count against quota, and that the team reads digests daily. This goes well beyond the minimal requirement.

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

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

The description is dense but every sentence carries useful information: what the tool does, when to use, when not to use, how to provide good feedback, the claim_token mechanism, rate limit, and cost. No fluff; well 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's moderate complexity (4 optional params, nested context object, no output schema), the description is complete. It explains the return behavior via claim_token, specifies the scope (only Pipeworx tools), and provides usage boundaries. All essential information is 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 descriptions cover 100% of parameters, so baseline is 3. The description adds meaning beyond the schema by explaining the claim_token usage in detail (pass it back as pipeworx_feedback({claim_token:'pwfb_…'}) to read status) and by advising not to paste the end-user's prompt (relevant to the message field). This additional 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 clearly states the tool's purpose: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It uses a specific verb ('Tell') and resource ('Pipeworx team'), and distinguishes itself from sibling tools like ask_pipeworx by focusing on feedback rather than asking questions.

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: for bug, feature/data_gap, or praise. It also gives a clear exclusion: do not use for tools from other MCP servers, and directs to file with that server instead. This is a strong actionable 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?

Beyond annotations (read-only, idempotent), description discloses data source (CF analytics-engine), privacy (no PII), and caching behavior (5min-1h). Adds value beyond structured fields.

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

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

Four sentences, each earning its place: output summary, three use cases, data source and privacy, caching. 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 tool with one optional parameter and no output schema, the description covers input semantics, output content, use cases, data provenance, and caching. Completely sufficient.

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

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

Schema coverage is 100% for the single parameter 'window' with enum values. Description adds semantic guidance: 'Shorter windows surface what's hot right now; longer windows show steady-state demand.' This enriches understanding beyond schema.

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

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

Description clearly states the tool returns top tools, top packs, and total call volume over a recent window. Verb 'returns' and resource are specific and distinct from sibling tools like 'discover_tools' or 'ask_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?

Explicitly lists three actionable use cases: discovering hot data sources, confirming canonical tools, and checking alignment. Does not directly mention alternatives or when not to use, but the scenarios are 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 goes beyond annotations by detailing internal algorithms: monotonicity checks, partition-sum filter, Jaccard similarity threshold, placeholder filtering, and fill check against live CLOB depth. It clearly states when signals are actionable and when not to trade.

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

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

The description is well-structured with clear sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) and a concise opening sentence. However, it is somewhat lengthy and includes detailed algorithm steps that could be summarized for an agent.

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 documents the response structure: opportunities[] with gap_pp, suggested_trade, reasoning, and partition_check details. It covers edge cases like placeholder filtering and low similarity skipping, and explains the fill check so the agent knows when to avoid a trade.

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?

While schema coverage is 100%, the description adds extensive context: explains what each parameter does, provides example values, and describes how the tool processes event slugs vs. topic queries, including the semantic anchor and partition filter 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 the tool finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It specifies different modes (no args, event, topic) and distinguishes 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 explains when to use each mode (event recommended for specific market, topic for cross-event scanning) and provides examples. It also advises using polymarket_fill_risk for custom sizing. However, it does not explicitly compare against all sibling tools or state when not to use this tool.

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

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

The description is highly transparent about internal behavior: model families, edge calculations, response segments, caching, and diagnostics. Annotations already indicate readOnly, openWorld, idempotent, and non-destructive, and the description adds extensive 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?

The description is very long and rambling, covering excessive technical detail. While detailed, it lacks conciseness and structure, with many non-essential sentences.

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

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

Given the tool's complexity (9 parameters, no output schema), the description is remarkably complete: it explains model families, edge calculations, response segments, tradeable-edge knobs, diagnostics, and even caching behavior. It covers all necessary context for an agent to use the tool effectively.

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

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

Schema coverage is 100%, so the schema already documents all parameters. The description adds value by explaining how knobs like slippage_pp and min_partition_leg_kelly work in context, providing extra insight 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 find opportunities where Pipeworx data disagrees with market price. It uses specific verbs and resources, and distinguishes itself from siblings like polymarket_arbitrage by focusing on discovery across multiple model families.

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

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

The description explains when to use the tool ('what should I bet on today' discovery), and describes tradeable-edge knobs for filtering. However, it does not explicitly state when not to use it or compare with alternatives.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds valuable behavioral context: snapshots are written on cache-miss, gaps mean no scan that day, history bounded by 60-day TTL, and decay computed from daily closes. 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 front-loaded with the core purpose and question it answers. It is fairly long but every sentence contributes necessary detail about the response structure and limitations. While not overly verbose, it could be slightly more concise without losing meaning.

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 extensively explains the response structure with detailed fields (tracked, expired, snapshot_dates including first_seen, trend, decay_pp_per_day, etc.). It also covers limitations like 60-day TTL and snapshot gaps. This fully compensates for missing 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?

The input schema has 100% coverage with basic descriptions for both parameters (days, window). The description adds meaningful context: explains 'days' as lookback with default 14 and max 30 (clamp 2-30 in schema), and 'window' as snapshot family with default '1wk'. It also clarifies how parameters affect the response structure (e.g., snapshot_dates depend on days). Some redundancy but 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 provides 'edge persistence and decay telemetry built from daily polymarket_edges snapshots' and answers the specific question of how long an edge has existed. It differentiates from sibling tools by focusing on persistence/decay rather than raw edges (polymarket_edges) or arbitrage (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?

The description implies when to use the tool (e.g., 'a fresh wide edge and a 3-week-old wide edge are different trades') and provides context about snapshots and data gaps. However, it does not explicitly state when not to use it or name alternative tools for comparison.

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

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

Annotations already indicate readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds valuable behavioral context: it 'walks the ladder' and returns specific fields like top_of_book, vwap_fill_price, slippage, etc. It also details basket mode returns and the risk of thin legs. 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 well-structured with clear sections for SINGLE-MARKET and BASKET modes, using bold for key terms. It is front-loaded with the main purpose. While somewhat lengthy, every sentence adds value given the tool's complexity. Minor redundancy is acceptable.

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

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

Given the tool's complexity (two modes, multiple return values) and the absence of an output schema, the description is remarkably complete. It explains all return fields for both modes, highlights risks (thin_legs, forced_directional_risk), and provides usage context. No significant 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 description coverage is 100%, but the description adds meaning beyond the schema. It explains the mutual exclusivity of 'market' and 'event' parameters, and clarifies 'size_usd' in basket mode as 'settlement notional — shares per leg, each paying $1 at resolution.' It also provides defaults and constraints, enriching the schema.

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

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

The description starts with 'Realizable-vs-theoretical edge check against live CLOB order-book depth,' clearly defining the tool's function. It distinguishes between single-market and basket modes, and the title 'polymarket_fill_risk' is descriptive. The purpose is specific and differentiated from sibling tools like polymarket_arbitrage and polymarket_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 explicitly states: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It provides when-to-use and when-not-to-use guidance, explaining risks like theoretical overround on thin books and partial basket fills converting arbs into directional positions.

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

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

The description adds significant behavioral context beyond annotations, including detailed explanations of safety fields (compatibility_warning, temporal_alignment, skipped counters) and the conditions under which spreads are meaningful. 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 well-structured with clear sections (purpose, modes, response, safety fields, caution). It is front-loaded and informative, though slightly lengthy. Every sentence adds value; minor redundancy could be trimmed.

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

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

Despite lacking an output schema, the description comprehensively explains the response structure (leg-by-leg prices, spreads, safety fields) and edge cases (compatibility warnings, temporal alignment, skipped comparisons). It is 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?

The description enriches understanding of all three parameters: it lists the 10 macro shortcuts for 'topic', explains that explicit tickers override the topic, and clarifies the purpose of each. Schema coverage is 100%, but the description adds valuable context.

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

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

The description clearly states the tool's purpose: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It distinguishes from sibling tools by focusing on cross-venue comparisons and explains the two modes (topic and explicit tickers).

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

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

The description explains when to use each mode, provides examples of topics, and warns that most pre-mapped topics return compatibility warnings, implying exploratory use. It does not explicitly compare to siblings but provides sufficient context for 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 declare readOnlyHint=true and idempotentHint=true. The description adds scoping details and pairing with remember/forget, which provides additional 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 three sentences, front-loaded with the main purpose, and every sentence adds value without any 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 the tool's simplicity and high annotation coverage, the description is complete enough. No output schema exists, but the behavior (retrieve value vs. list keys) is clearly conveyed.

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 one parameter 'key'. The description reinforces the schema by explaining omitting the key lists all saved keys, adding value beyond the schema.

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

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

The description clearly states the tool retrieves a value previously saved via remember or lists all saved keys, using specific verb+resource. It distinguishes itself from siblings like remember and forget.

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

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

The description provides explicit use cases (e.g., looking up user's target ticker, address, research notes) and mentions scoping. It doesn't explicitly state when not to use, but context is clear.

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

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

The description describes a mutating operation ('Set mark_read:true to flag returned events read'), which contradicts the readOnlyHint=true annotation. This is a direct contradiction, making the description misleading about the tool's 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?

The description is a single, well-structured paragraph of 4 sentences, front-loaded with the main purpose. Every sentence adds value, with no redundancy or filler.

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

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

The description explains return fields, filtering, and polling suitability, but omits pagination and error handling. The contradiction with annotations further reduces completeness, as the behavioral model is inconsistent.

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 useful examples (e.g., 'sec_8k' for type, ISO timestamp for since) and clarifies the behavior of mark_read, going beyond 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 tool's purpose: 'Pull fired events from your subscription feed' with a specific verb and resource. It details the return fields and filtering options, making it distinct from siblings like list_subscriptions.

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

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

The description mentions an alternative access method (GET registry.pipeworx.io/alerts.json) but does not provide explicit guidance on when to use this tool versus sibling tools like subscribe or list_subscriptions. Usage context is implied but not explicitly stated.

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-only operation. Description adds behavior: fans out to multiple sources, fallback from GDELT to GNews on rate limits/5xx, USPTO soft-fails, and return structure. 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?

Paragraph is dense but well-structured: opens with example queries, then sources, fallbacks, parameter hints, return format, and sibling reference. Every sentence adds value, though slightly 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?

Despite no output schema, description fully covers return format (changes[], total_changes, citation URIs), failover behavior, and API status (USPTO sunset). Explicitly references sibling tool. Complete 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 has 100% coverage but description adds: relative shorthand examples for 'since' (e.g., '30d'), ticker/CIK for 'value', and notes only 'company' supported for 'type'. Goes beyond schema with usage recommendations.

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 states it's a 'change feed for a company in the last N days/weeks/months' using example queries, specifies sources (SEC, GDELT/GNews, USPTO), and explicitly distinguishes from sibling 'entity_profile' for static profiles.

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 usage context with example queries, explains temporal window via 'since', and gives explicit alternative ('Use entity_profile instead when you want the static profile').

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

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

Adds context beyond annotations: scoped by identifier, persistent vs. 24-hour retention for anonymous sessions. No contradiction with annotations (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?

Efficient but thorough: front-loads purpose, then usage, then behavioral details, then sibling ties. 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?

Covers purpose, usage, behavior, and pairing; no output schema needed as return is implicit. Lacks error handling but overall sufficient.

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

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

Schema coverage is 100%, and description adds example key patterns and explains value as any text, enriching the parameter 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 saves data for later reuse, with concrete examples (resolved ticker, target address). It distinguishes from siblings recall and forget by naming them explicitly.

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

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

Explicitly says when to use (discover something worth carrying forward) and pairs with recall/forget for retrieval/deletion, 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 already indicate readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, but the description adds substantial behavioral context: graceful degradation (if GLEIF/OpenFIGI unavailable, EDGAR identifiers still return), cascading through multiple endpoints, labeling identifiers with their source, and explicitly reporting unresolved identifiers. It also explains the ISIN-to-LEI mapping for non-US issuers, which is beyond the structured 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 packed with valuable details. It is organized into a coherent flow from purpose to supported types to fallback behavior. While verbose, every major section earns its place; however, the length could be reduced by breaking into bullet points or subsections for easier scanning. The front-loading with example queries is 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 having no output schema, the description covers return behavior well: identifiers are labeled with their source, unresolved identifiers are explicitly listed under 'unresolved', and fallback behavior is described. It also explains the internal cascade and the types of entities handled. This provides a complete picture for an agent to know what to expect and how to handle partial failures.

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

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

Although the schema covers both parameters 100%, the description significantly enriches their meaning. For 'type', it expands on what 'company' and 'drug' return, including specific identifier systems (CIK, LEI, FIGI, RxCUI). For 'value', it lists accepted input formats (ticker, CIK, ISIN, company name, brand/generic) and adds the nuance that an ISIN resolves to the legal entity via GLEIF mapping. This goes well beyond the schema's brief descriptions.

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

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

The description clearly states the verb 'resolve' and the resource 'user-spoken NAME to canonical/official identifiers'. It provides multiple example queries ('What's the ticker for…', 'find the CIK for…') and explicitly distinguishes itself from sibling tools by focusing on name-to-ID resolution, a unique capability in the sibling list.

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

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

The description gives explicit guidance: 'Use FIRST whenever you have a name but need an ID.' It also details the supported types (company, drug) and what identifiers are resolved, helping the agent choose correctly. It even notes that using this tool replaces 2-3 manual lookups, reinforcing its role as a primary lookup utility.

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 that it internally calls 'ai_visibility_check' for each entity, ranks results, and returns a ranked list with score, confidence, and signal density. This adds significant value beyond the annotations (readOnlyHint, etc.) which alone don't describe the process.

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

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

Three sentences with no filler. First sentence states purpose, second explains mechanism, third gives concrete use case. Every sentence provides essential 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?

Given no output schema, the description communicates the return format (ranked list with score, confidence, signal density). It also covers parameters and behavior. Minor gaps: no mention of error handling for API keys or limits on model options, but overall sufficient.

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

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

Schema coverage is 100%, but the description adds meaning: it explains that the first entity in the array is treated as the 'subject' for narrative, and clarifies model choices and API key usage for 'anthropic'. This goes beyond the schema descriptions.

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

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

The description uses specific verbs ('Compare', 'Probes', 'ranks', 'surfaces') and clearly states the resource ('AI visibility across multiple entities'). It distinguishes from sibling 'ai_visibility_check' by emphasizing side-by-side comparison and ranking.

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

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

Provides clear context for use ('competitive AI-marketing audits') with an example question. Although it doesn't explicitly state when not to use, the sibling tools include 'ai_visibility_check' for single-entity checks, implying alternatives.

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

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

Beyond annotations (readOnly, openWorld, idempotent), the description discloses critical behavioral traits: bundlephobia timeout (5-30s), partial failure handling (sources_failed field), and that the tool fans out across multiple sources. 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 front-loaded with the main purpose but becomes verbose (246 words) detailing return fields. Without an output schema, this is somewhat justified, but could be more concise by listing return fields in a bullet format.

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 (summary block fields, per-advisory detail, links, recent versions). It also covers edge cases (partial failures, timeouts), making it complete for an AI agent to understand the tool's behavior.

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

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

Schema coverage is 100% with parameter descriptions. The description adds meaningful context: 'Scoped packages (e.g. "@types/node") are accepted' and default behavior for version. This enhances the schema without redundancy.

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

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

The description starts with a specific verb ('scan') and resource ('npm package'), clearly indicating it's a composite check combining deps.dev and bundlephobia. This distinguishes it from generic research tools in the sibling list (e.g., deep_research, 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 usage guidance: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"'. Also excludes other ecosystems: 'NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly', providing alternatives.

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

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

Discloses embedding model (BGE-base-en), similarity metric (cosine), window size (500-char overlapping), and character cap (200K chars with truncation flag). Annotations already indicate read-only and idempotent, but description adds critical behavioral details 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?

Four sentences, front-loaded with purpose and key constraints. 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?

Covers input, output (top-N passages with offsets and scores), internal mechanics, limits, and pairing guidance. Despite no output schema, description gives sufficient return details.

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, but description adds meaningful context: 'pass the text you already pulled' for text parameter and provides natural-language query examples. 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?

Clearly states 'semantic search INSIDE a fetched record' with specific examples (SEC 10-K, article). Distinguishes from sibling tools by mentioning pairing with ask_pipeworx_grounded.

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

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

Explicitly instructs use when the record is too big for the prompt and explains context-saving benefit. Mentions pairing with a sibling tool, but does not explicitly state when not to use.

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

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

Description adds behavioral context beyond annotations: returns subscription id, OAuth requirement, delivery channel limitations (SMS cap, webhook auto-disable), and webhook HMAC signing. 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?

Single focused paragraph that front-loads purpose. Covers all essential information without fluff. Slightly dense but still readable; could be improved with bullet points for types.

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 purpose, return value, auth requirements, all type-specific parameters with examples, delivery options including limitations, and webhook security details. No missing context despite complexity and 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?

Extends schema descriptions with concrete examples (e.g., sec_8k: items:['5.02'] for officer change, polymarket_edge params, delivery webhook secret). Despite 100% schema coverage, description adds substantial value for correct parameter usage.

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 'Create a proactive monitoring subscription to a live-data event stream. Returns the new subscription id.', which is a specific verb+resource. It distinguishes from sibling tools like list_subscriptions and unsubscribe.

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

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

Provides context for when to use: setting up proactive monitoring. Specifies requirement for Pipeworx OAuth account. Lists supported types and delivery channels with constraints. Does not explicitly state when not to use, but siblings provide alternatives.

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

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

The description adds significant context beyond annotations: it explains the return format (category-bucketed example questions with tool+argument shape), that it draws from a live catalog, and how topic filtering works. 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 somewhat lengthy but well-structured, starting with example queries and ending with usage guidance. Every sentence adds value, though minor trimming could improve conciseness.

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

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

Despite no output schema, the description fully covers what the tool returns (category-bucketed examples with tool shapes) and how to use it. For a single-parameter tool, this is complete and sufficient.

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

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

With 100% schema coverage and one optional parameter, the description adds meaningful detail: explains the effect of omitting vs including topic, provides example topic values, and clarifies the default behavior.

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: returns category-bucketed example questions to help users explore what Pipeworx can do. The verb 'suggest_questions' is specific, and it distinguishes itself from sibling tools by positioning itself as the onboarding entry point.

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

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

Explicitly says 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' It provides clear context for when to use, though it does not explicitly state 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?

Adds value beyond annotations: ownership enforcement and soft-delete behavior. Annotations indicate non-destructive; description clarifies it's a deactivation, not deletion.

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 redundancy, front-loaded with action and resource.

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 covers the tool's effect for a single-parameter tool with no output schema. Explains historical event availability.

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?

Single parameter 'id' with 100% schema coverage. Description adds context that id is returned by subscribe, aiding usage.

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 'Cancel a subscription by id'—specific verb and resource. Distinguishes from siblings like subscribe and list_subscriptions.

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

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

Mentions ownership enforcement and deactivation behavior, implying context for when to use recent_alerts. No explicit 'when not to use', but sufficient 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 readOnly, openWorld, and idempotent, but the description adds critical behavioral context: the structured SEC/EDGAR fast path vs. grounded fallback, the exact verdict enum, and the crucial semantic distinction between could_not_verify (check did not happen) and unsupported (no source exists). It even warns callers not to treat could_not_verify as evidence, which is exactly the kind of disclosure that annotations cannot express.

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

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

Although the description is long, it is front-loaded with the most recognizable usage examples and every segment serves a purpose: trigger phrases, when-to-use, routing logic, return contract, and the crucial caller warning about could_not_verify. The structure is scannable and the density 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?

Despite the absence of an output schema, the description spells out the verdict values, the citation mechanism, the reasoning field, and the semantics of failure states (could_not_verify vs. unsupported). It also justifies why this tool replaces multiple sequential calls, giving callers a complete mental model of what the tool will do and return.

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

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

Schema description coverage is 100%, so the schema already fully documents claim and tolerance_pct. The main description adds important context about exact percent-delta math and the fast path, but it does not extend the parameter-level semantics beyond what the schema provides. With complete schema coverage, the baseline 3 is appropriate.

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

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

The description opens with concrete natural-language triggers ("Is it true that…", "fact check") and a specific verb phrase: "natural-language claim verification against authoritative sources." It further distinguishes the tool's scope by separating company-financial claims (SEC EDGAR + XBRL fast path) from any other factual claims, making its purpose unambiguous relative to sibling tools 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?

The description explicitly states when to use: "Use whenever the agent needs to check whether something a user said is factually correct." It also clarifies the internal routing for financial vs. non-financial claims. However, it does not explicitly name an alternative for non-factual or general questions, so the when-not/alternative guidance is only implied.

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