South Africa Tenders

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

Annotations already declare the tool as read-only, idempotent, and non-destructive. The description adds critical behavioral details: default model is free Workers AI, optional Anthropic requires a BYO key, and the return structure includes per-model score, confidence, signals, and raw_response along with a combined view. 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?

Four sentences front-load the core purpose, then efficiently cover optional parameters, return format, and use cases. No redundant or extraneous 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?

No output schema exists, so the description compensates by detailing the return structure (score, confidence, signals, raw_response, combined view). All four parameters are explained with examples. However, it does not specify pagination or limits, which could matter for large-scale probing.

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

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

With 100% schema coverage, the baseline is 3. The description adds value by explaining the default model, that _apiKey is passed through transparently, and that context disambiguates entities. This goes beyond the schema's descriptions.

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

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

The description clearly states the tool probes LLMs for knowledge about entities and generates a visibility score (0-100) per model. It specifies the verb 'probe', the resource 'LLMs', and the outcome, distinguishing it from sibling tools like scan_competitor_ai_presence by covering any entity type.

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

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

The description lists specific use cases (AI-marketing audits, pre-launch brand checks, competitive monitoring) that imply when to use. It does not explicitly state alternatives or when not to use, but the use cases provide sufficient guidance for appropriate invocation.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds value by explaining that the tool routes to 4,819 tools and returns citation URIs, providing behavioral context beyond the annotations. However, it does not detail error handling or rate limits.

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

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

The description is front-loaded with the key directive and is well-structured, but slightly verbose with redundant phrases. It efficiently uses examples and sibling references.

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 when to use, what it does (routes question, returns answer with citations), and provides alternatives. Lacks details on error handling or unsupported queries, but the complexity of the tool is addressed adequately.

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

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

Schema coverage is 100% with descriptions for all parameters (primarily aliases for 'question'). The description provides examples and explains that the question is in natural language, but adds little semantic depth beyond the schema 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 explicitly states that the tool routes questions to a wide array of specialized tools across thousands of sources, returning structured answers with citation URIs. It clearly differentiates from siblings like ask_pipeworx_grounded and deep_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?

Offers explicit guidance on when to use this tool ('PREFER OVER WEB SEARCH', 'START HERE for most questions') and when to step up to alternatives (ask_pipeworx_grounded for single answers, deep_research for broad questions). Examples further clarify usage scenarios.

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

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

The description adds significant behavioral detail beyond annotations: it explains the extra LLM call cost, the refusal mechanism with specific reasons, and the strict evidence extraction. Annotations indicate read-only and non-destructive behavior, which is consistent with the description.

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

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

Every sentence serves a purpose: defining tool mode, describing mechanism, listing return fields, specifying use cases, and noting cost trade-off. It is dense but well-structured and front-loaded with the primary purpose.

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

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

Despite lacking an output schema, the description comprehensively documents the return format (answer, evidence, confidence, source, fetched_at, refusal_reason) and all possible refusal reasons. It also covers the cost comparison with the sibling tool, making it complete for a grounded query tool.

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

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

Schema description coverage is 100%, so baseline is 3. The description mentions that aliases (q, text, etc.) are accepted, but this is already fully covered in the schema descriptions. No additional parameter semantics are provided beyond what the schema contains.

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

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

The description clearly states the tool provides a 'Hallucination-resistant answer mode for high-stakes reads' and explicitly distinguishes it from the sibling 'ask_pipeworx' tool by noting it extracts answers only from tool results and avoids invention.

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

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

The description provides explicit guidance: use for high-stakes reads where answers will be quoted or acted on (e.g., financial verdicts, legal claims), and prefer the cheaper 'ask_pipeworx' for casual lookups. It also gives concrete examples and refusal scenarios.

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

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

Annotations indicate readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false. The description goes far beyond annotations by detailing resolution process, classification, fan-out, market_match_confidence, parent_event extraction, news fallback, safety short-circuits (low confidence, closed markets), wide-spread handling, and resolution-rule risk. This is exemplary transparency.

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

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

The description is very long (multiple paragraphs) and contains extensive detail that might be better placed in output schema or separate documentation. It is front-loaded with purpose and usage, but the sheer length reduces conciseness. However, the structure is logical and organized.

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

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

Given the complexity of the tool and no output schema, the description thoroughly covers all aspects: input handling, fan-out examples for many categories, response shapes (market, analysis, evidence), resolver contract, parent event extractor, news fallback, safety mechanisms, and resolution rule risk. It is complete and leaves no major gaps.

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

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

Schema coverage is 100% with all parameters documented. The description adds valuable context: clarifies input formats (slug, URL, text), explains depth values ('quick' vs 'thorough'), and describes the default and effect of include_raw. This adds meaning beyond the schema.

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

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

The description clearly states that the tool researches a Polymarket bet by pulling relevant Pipeworx data. It specifies the verb (research), resource (bet/market), and input types (slug, URL, question text). It also distinguishes from sibling tools like polymarket_edges and polymarket_arbitrage by focusing on individual 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 states use cases: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It provides detailed examples of fan-out for different bet types. However, it does not explicitly say when NOT to use this tool or list alternative tools for different scenarios, which would improve decision-making.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds substantial context: it uses SEC EDGAR/XBRL for companies, handles off-calendar fiscal years, returns sorted results, and includes citation URIs. This goes well beyond annotations, providing a clear behavioral model.

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

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

The description is front-loaded with trigger phrases and provides detailed, useful information without wasted words. It is well-structured but slightly verbose (e.g., parenthetical examples could be condensed). Still, 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?

For a tool with two parameters and no output schema, the description adequately explains the return format (paired data + citation URIs, sorted results), data sources, and limitations (off-calendar fiscal years). It provides enough context for an agent to understand input, behavior, and output.

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

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

Although schema coverage is 100%, the description enriches meaning by explaining that 'company' values are tickers/CIKs and 'drug' values are names, and by giving concrete examples (e.g., ['AAPL','MSFT'], ['ozempic','mounjaro']). This clarifies parameter usage beyond the schema's basic type/description.

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

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

The description opens with explicit trigger phrases like 'Compare X and Y' and clearly states it performs side-by-side comparisons of 2-5 companies or drugs in a single call. It specifies the verb (compare), resource (entities), and distinguishes from sequential single-entity lookups, making the purpose unmistakable.

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

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

The description gives strong usage guidance by listing common user intents and explicitly stating 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.' It explains what happens for each type (company vs drug) and mentions replacing 8-15 sequential lookups, but does not explicitly mention when not to use or provide direct alternatives for single entity queries.

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

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

Annotations already indicate readOnly, openWorld, idempotent, non-destructive. Description adds critical context: account requirement, paid plan for certain depths, expected 15-60s latency, returns findings packet with gaps[]. No contradiction with annotations.

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

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

All sentences are informative and front-loaded with the critical account requirement. Efficiently covers purpose, prerequisites, alternatives, and limitations without redundancy.

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

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

Despite complexity (parallel execution, many tools, structured data sources), description fully explains what the tool does, how it works, prerequisites, limitations, and return format (findings packet with evidence, confidence, source, fetched_at, citation, gaps). No output schema needed.

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

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

Schema coverage is 100%. Description adds semantics: question is natural language and broad/multi-part is fine; depth enum explained (quick=3, standard=5, thorough=8). Provides practical usage guidance.

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

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

The description clearly states the tool performs 'grounded multi-source research across Pipeworx's 1259 STRUCTURED data sources' and 'decomposes your question into focused facets, routes each to the right one of 4,819 tools IN PARALLEL'. It distinguishes from siblings like ask_pipeworx by specifying it is for broad/multi-part questions over structured data, not single lookups or news.

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 instructions: account required, use ask_pipeworx if not signed in; for breaking news prefer ask_pipeworx; best for broad/multi-part questions over structured data; single lookup use ask_pipeworx. Also notes depth 'thorough' needs paid plan.

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 value beyond annotations by explaining that it returns top-N tools with full input schemas and curated examples, and that results are ready to call directly. No contradictions with annotations (readOnlyHint, idempotentHint, etc.). It also lists categories of data sources covered.

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

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

The description is concise, front-loaded with purpose, and every sentence provides essential information. No redundant or filler content.

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

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

For a discovery tool with no output schema, the description adequately explains the return format (names, descriptions, schemas) and usage context. It could mention pagination or limit handling but is complete enough for the tool's purpose.

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

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

Schema coverage is 100%, so baseline is 3. The description adds minimal new parameter semantics beyond what's in the schema, though it reinforces aliases and provides examples. It does not specify constraints 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 'Find tools by describing the data or task' and distinguishes itself from sibling tools by specifying it should be called first to discover available tools, not to directly answer queries. It explicitly mentions the verb-resource pair and gives specific domains.

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

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

The description explicitly says 'Use when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST when you have many tools available and want to see the option set'. It provides clear context but does not explicitly state when not to use it (e.g., if you already know the tool), though that is implied.

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

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

Annotations declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds extensive behavioral context beyond these: it fans out across multiple sources (SEC, XBRL, USPTO, news, GLEIF), returns specific data fields, notes that patents soft-fails after May 2025, and explains the data sources. 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 every sentence adds value. It starts with example user queries, which is helpful for the agent. While it could be slightly more concise, the information density is high and well-organized. No wasted 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 complexity of the tool (multiple data sources, various outputs), the description is remarkably complete. It enumerates exactly what is returned (CIK, company_name, recent_filings with URIs, fundamentals with specific fields, patents with limitations, news via fallback, LEI). Without an output schema, the description adequately covers return values and 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%. The description adds meaning beyond the schema: explains that type can only be 'company' for now, value must be a ticker or zero-padded CIK, and explicitly states that names are not supported. It provides examples of valid inputs (e.g., 'AAPL', '0000320193'). This fully compensates for any lack of detail in 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 provides a full cross-source profile of a US public company in one parallel call. It lists specific user queries like 'Tell me about X' and 'company profile for Microsoft', and details the output components (CIK, filings, fundamentals, patents, news, LEI). It distinguishes from siblings by explicitly preferring over chaining single-pack lookups and mentioning resolve_entity for names.

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

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

Explicitly states when to use: when the user asks for a holistic view of a US public company. It says to prefer this tool over chaining multiple individual lookups. It also specifies what not to do: names are not supported, and advises using resolve_entity first if only a name is available. Alternatives are clearly provided.

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

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

Annotations already provide destructiveHint=true and idempotentHint=true. Description confirms deletion but adds no extra behavioral context beyond what annotations convey, such as side effects, permissions, or error handling.

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: first states action, second gives usage guidance. No fluff, front-loaded with key information. Every sentence earns its place.

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

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

For a simple 1-parameter tool with full schema coverage and informative annotations, the description covers purpose, usage, and pairing with siblings. It is complete enough for an agent to select and invoke correctly.

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

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

Schema coverage is 100% with parameter description 'Memory key to delete.' Description says 'by key,' which adds no new meaning. Baseline 3 for high coverage.

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

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

Description starts with 'Delete a previously stored memory by key.' It clearly states the verb (Delete), resource (memory), and scope (by key). It distinguishes from siblings by mentioning pairing with remember and recall, which are complementary tools.

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

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

Explicit usage guidance: 'Use when context is stale, the task is done, or you want to clear sensitive data the agent saved earlier.' Also suggests pairing with remember and recall, giving context on when to use vs. 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 (readOnly, idempotent, non-destructive) are augmented by the description's mention of fetching, extracting, and emitting markdown format, adding process details without contradiction.

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

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

Three sentences efficiently cover what, how, and when to use. No wasted words; front-loaded with the key action.

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 2 parameters and no output schema, the description covers purpose, input, output format, and use cases, making it fully actionable.

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

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

Schema covers both parameters with descriptions, so baseline is 3. The description adds no extra meaning to the parameters but notes the output format, which is peripheral.

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

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

The description clearly states the tool generates an llms.txt file for a URL, using specific verbs like 'generate', 'fetches', 'extracts', and 'emits'. It distinguishes itself from siblings by focusing on this unique task.

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

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

Explicit use cases are provided: getting a client's site indexed, drafting for own project, auditing competitor. No exclusions or alternatives mentioned, but the context is clear.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the description's additional details (return fields) are complementary. No contradictions.

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

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

Two efficient sentences: first states function and return fields, second provides usage guidance. 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 list tool with rich annotations and clear return fields, the description is sufficiently complete. It explains purpose, fields, and usage context.

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

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

Schema coverage is 100% for the single boolean parameter 'include_inactive'. The description does not add extra meaning beyond what the schema provides, meeting the 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 'List the caller's active subscriptions' with a specific verb and resource. It distinguishes itself from siblings 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?

Provides explicit guidance: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This clarifies when to use the tool, though it doesn't explicitly mention when not to use it.

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

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

Beyond annotations (readOnlyHint false, etc.), description discloses rate-limiting (5 per identifier per day), free usage, and that feedback is read by team and affects roadmap. 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?

Single paragraph with clear structure: purpose first, then guidelines, then details. Every sentence adds value; 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?

Complete for a feedback tool: covers what, how to structure, constraints (rate limit, quota). No output schema needed.

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

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

Schema coverage is 100%, but description adds meaning: explains enum values with examples, clarifies context object structure, and specifies message format (1-2 sentences, 2000 chars max).

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 specifies four feedback types (bug, feature/data_gap, praise) and differentiates from sibling tools (no other feedback tool).

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

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

Explicitly provides when to use: bug for wrong/stale data, feature/data_gap for missing tools, praise for positive experiences. Also advises on what to include (describe in terms of tools/packs, avoid pasting user prompts) and notes rate limits and quota.

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

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

Beyond annotations (readOnlyHint, idempotentHint, etc.), the description adds valuable behavioral context: data source (CF analytics-engine), no PII, cached 5min-1h, and what aggregates are returned. No contradictions with annotations.

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

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

The description is concise, with three well-structured sentences: purpose, use cases, technical details. It is front-loaded and avoids redundancy. Could be slightly more compact, but no significant waste.

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

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

Given the tool's simplicity (1 optional parameter, no output schema), the description provides sufficient context: what is returned (top tools, packs, call volume), caching behavior, and data source. No gaps for effective usage.

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

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

The schema already describes the 'window' parameter with enum values and a baseline description (100% coverage). The description adds further semantics: 'Shorter windows surface what's hot right now; longer windows show steady-state demand', which helps the agent choose appropriately.

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

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

The description clearly identifies the tool's purpose: returning top tools, packs, and call volume over a recent window. This distinguishes it from siblings like 'discover_tools', which likely focuses on discovering available tools rather than trending activity.

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 three concrete use cases, giving the agent clear guidance on when to invoke this tool. However, it does not explicitly mention when not to use it or suggest alternatives (e.g., 'discover_tools' for general discovery).

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

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

Beyond annotations (readOnlyHint, idempotentHint, etc.), the description details scanning top 200 markets, child market walking, Jaccard similarity threshold, placeholder filtering, and fill check with CLOB depth. No contradiction with annotations.

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

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

Well-structured with clear sections and front-loaded key info. However, the description is lengthy; some details (e.g., partition check explanation) could be slightly condensed without losing value.

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

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

No output schema, but description fully explains return fields (opportunities[], partition_check, fill_check). Covers edge cases (skipped_low_similarity, placeholder filter) and references sibling tool for custom sizing. Complete for the tool's complexity.

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

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

Schema coverage is 100%, but description adds significant value: explains that 'event' accepts full URLs, 'topic' triggers cross-event search, and noargs triggers trending scan. Enriches parameter meaning beyond 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?

Clearly states it finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. Distinguishes between modes (trending_scan, event, topic) and differentiates 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?

Provides explicit when to use each mode: no args for trending scan, event for a specific market, topic for cross-event scanning. Also advises when not to trade based on fill check and refers to polymarket_fill_risk for custom sizing.

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

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

Beyond annotations (readOnlyHint, idempotentHint), the description exhaustively discloses behavioral traits: cache behavior (1h KV cache), response structure with diagnostics, filter skips, model family methodology, and edge calculation details. No contradictions with annotations.

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

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

The description is long but well-structured: starts with purpose, then details model families, response fields, and knobs. It front-loads the key information, though some details (like exact model parameters) could be abbreviated without loss.

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

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

Despite no output schema, the description thoroughly explains the response structure (by_segment segments, diagnostics, fed fields) and cache behavior. It covers all necessary context for an agent to use the tool correctly, including edge cases for empty segments.

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

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

All 9 parameters have schema descriptions (100% coverage), and the description adds substantial extra meaning: examples, justifications, and context (e.g., slippage explanation, min_liquidity recommendation, min_partition_leg_kelly rationale). This significantly aids correct parameter selection.

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 top Polymarket markets and returns opportunities where Pipeworx data disagrees with market price, with a specific use case 'what should I bet on today'. It distinguishes from sibling tools by focusing on edge scanning 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 provides clear context for when to use the tool ('agents discover opportunities without paging hundreds of markets') but does not explicitly mention when not to use it or point to alternative sibling tools. The usage is implied well but lacks explicit exclusions.

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

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

Annotations already mark the tool as read-only, idempotent, and non-destructive. The description adds details on data source (snapshots), time-series computation, and caveats (gaps mean no scan). It also explains the output structure comprehensively.

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 logically structured with sections for purpose, output fields, and limits, but is verbose with parenthetical explanations and could be more concise. The key information is front-loaded.

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

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

Despite no output schema, the description fully specifies the return structure (tracked, expired, snapshot_dates), explains each field and computed metric, and covers limitations and data gaps. This is comprehensive for agent use.

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

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

Schema coverage is 100%, and the description adds default values and maximum for 'days', default for 'window', and contextual information about the 60-day TTL. This provides meaning beyond the schema.

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

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

The description clearly states the tool provides edge persistence and decay telemetry, answering whether an edge is new or old. It uses a specific verb ('provides') and resource ('daily polymarket_edges snapshots'), but does not explicitly differentiate from the sibling tool 'polymarket_edges', which is the data source.

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

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

The description implies usage for evaluating edge longevity and decay, and includes LIMITS about history depth and decay computation. However, it lacks explicit guidance on when to use this tool vs alternatives, such as when to prefer polymarket_edges or bet_research.

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

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

Annotations declare read-only and idempotent. Description adds concrete behavior: walks the order book ladder, checks per-leg fills, returns detailed verdict and risk fields. No contradiction with annotations, and adds significant context beyond the 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?

Well-structured with clear sections for each mode and usage guidance. Front-loaded with purpose. While dense, every sentence adds value for a complex tool; minor improvement possible by trimming redundant phrasing.

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

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

Covers both modes thoroughly with return fields, risk explanations, and use case. Missing error handling or failure modes, but no output schema so description bears full burden; adequate for a check tool with moderate complexity.

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

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

Schema coverage is 100%. Description goes beyond schema by explaining mode-dependent meanings for 'side' (default auto in basket based on partition sum) and 'size_usd' (spend vs target proceeds vs settlement notional), adding practical 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 'Realizable-vs-theoretical edge check against live CLOB order-book depth', specifies two modes (single-market and basket) with detailed outputs, and distinguishes itself from siblings by advising use before polymarket_arbitrage or polymarket_edges trades above $500.

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

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

Explicitly states when to use (before arb or edge trades >$500) and explains the risk of partial fills and unhedged positions, but does not explicitly list alternatives or exclusions for when not to use.

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

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

Annotations (readOnlyHint, idempotentHint) are consistent with read-only behavior. The description adds rich behavioral context: explains safety fields (compatibility_warning, temporal_alignment, skipped counters), clarifies when spreads are meaningless, and warns about the rarity of tradeable spreads—going well beyond annotations.

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

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

The description is well-structured with clear sections (TWO MODES, RESPONSE, SAFETY FIELDS) and front-loaded purpose. While each sentence adds value, the length is slightly above average; could be more concise without losing 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 fully explains the response structure (leg-by-leg prices, top_spreads_pp, compatibility_warning, temporal_alignment, skipped counters) and handles edge cases (non-equivalent bet shapes, temporal misalignment). Complete 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 coverage is 100% with clear parameter descriptions. The description adds value by explaining the two-mode narrative and the meaning of 'topic' shortcuts, and by clarifying that explicit parameters override the mapped side. This enriches semantics beyond the schema alone.

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

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

The description clearly states 'Cross-venue spread between Kalshi and Polymarket for the same resolving question', specifies two distinct modes (topic shortcuts and explicit parameters), and distinguishes itself from sibling tools like polymarket_arbitrage by focusing on cross-venue comparison.

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

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

Explicitly guides when to use topic vs explicit mode, warns about compatibility_warning conditions (non-equivalent bet shapes, unrelated events), temporal alignment requirement, and cautions that most pre-mapped topics are not tradeable—providing comprehensive when-to-use and when-not-to-use guidance.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds context about scoping (anonymous IP, BYO key hash, account ID) which is beyond the annotations, and confirms the tool is for retrieval, not mutation.

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

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

The description is two substantive sentences front-loaded with the key operation. Every sentence contributes essential information without redundancy.

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

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

The description covers purpose, usage, scoping, and sibling relationships. With no output schema, it could explicitly mention the return format (value or list), but the tool is simple enough that it's not a major gap.

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

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

Schema coverage is 100% and the schema already describes that omitting key lists all keys. The description adds value by explaining the purpose (looking up context) and scoping, slightly improving over the 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 action ('retrieve' or 'list') and the resource (saved memories via remember). It distinguishes itself from siblings like 'remember' and 'forget' by explicitly describing the retrieval and listing behavior.

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

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

The description provides explicit usage context: to look up previously stored context (ticker, address, notes) without re-deriving it. It also mentions scoping to an identifier and pairing with remember/forget. It lacks explicit when-not-to-use instructions but is still strong.

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

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

Annotations indicate safe read (readOnlyHint, idempotentHint, non-destructive). Description adds specific behavior: returns most recent alerts, carries source/citation_uri/payload, filtering by type/since, and the mark_read side effect. 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?

Two sentences covering main action, return fields, filters, and mark_read behavior. No redundant words. Front-loaded with primary 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?

With 5 optional parameters and no output schema, description covers what the tool returns, key parameter behaviors, and alternative access. Sufficient for an agent to invoke correctly.

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

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

Schema coverage is 100%. Description adds meaning: 'type' filter example ('sec_8k'), 'since' as ISO timestamp, 'mark_read' effect on next call, and limit range implied (1-200, default 50). Does not detail 'unread_only', but overall 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?

Begins with 'Pull fired events from your subscription feed,' clearly specifying the verb and resource. Notes return fields (source, citation_uri, raw payload). Distinguishes from siblings like list_subscriptions by focusing on event retrieval from a persisted feed.

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: 'Polls work fine; the same feed is also at GET registry.pipeworx.io/alerts.json for scripts and dashboards.' Offers alternative access. Explains mark_read behavior for subsequent calls. Does not explicitly exclude when not to use, but gives 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 readOnlyHint, openWorldHint, idempotentHint, and destructiveHint as true/false appropriately. The description adds extensive behavioral context: it fans out to three sources in one parallel call, specifies GDELT is preferred with GNews as fallback on rate limits or 5xx, notes USPTO PatentsView API sunset (soft-fail), and describes the structured return format with citation URIs. No contradiction with annotations.

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

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

The description is a single paragraph but packs substantial detail without redundancy. It front-loads with user-facing query examples, then covers sources, parameters, and fallback behavior. It could be slightly more organized (e.g., bullet points for sources), but it remains efficient and scannable. Every sentence contributes 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 the tool's complexity (multi-source, fallback, API sunset, structured return), the description covers all necessary aspects: sources and their priority, parameter formats, return shape, and an explicit alternative for static data. There is no output schema, but the description outlines the return structure adequately (changes[] grouped by source + total_changes count + citation URIs). An agent has sufficient information to invoke the tool correctly.

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

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

Schema coverage is 100% (all 3 params described in schema), so baseline is 3. The description adds value by: clarifying that `type` is currently only 'company', explaining the ISO date vs. relative shorthand formats for `since` with examples ('7d', '30d', '3m', '1y'), and suggesting typical monitoring values ('30d' or '1m'). It also explains `value` accepts 'ticker or zero-padded CIK'. 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 starts with example queries ('What's new with X', 'updates on Acme') and clearly states the tool provides a 'change feed for a company in the last N days/weeks/months in ONE parallel call'. It enumerates exactly which sources are covered (SEC EDGAR, GDELT/GNews, USPTO) and explicitly distinguishes from the sibling `entity_profile` tool by contrasting 'static profile' vs. change feed.

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

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

The description gives clear when-to-use guidance: for 'latest on Y', 'what happened to Z', 'news on Tesla recently', etc. It explicitly says 'Use entity_profile instead when you want the static profile (filings + fundamentals + LEI + patents) regardless of window', which provides a direct alternative and exclusion. No confusing usage scenarios.

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

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

Annotations already provide idempotentHint (true) and destructiveHint (false). The description adds valuable context: key-value pair scoped by identifier, persistence duration (24hrs for anonymous, persistent for authenticated). No contradictions.

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

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

The description is concise (4 sentences) and front-loaded. Every sentence adds value, no wasted words. Structure is logical: purpose, usage, storage details, complementary tools.

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 could mention what is returned (e.g., success indication), but it covers purpose, usage, and behavioral traits adequately. Persistence details are a plus. Slight gap in return value info.

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 describes parameters with examples. The description adds context about storage but doesn't add significant new semantics beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose: 'Save data the agent will need to reuse later' with specific examples (ticker, address, preference). It distinguishes from siblings like recall and forget by naming them.

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

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

The description provides clear guidance on when to use the tool ('when you discover something worth carrying forward') and mentions complementary tools (recall, forget). However, it does not explicitly state when not to use it or list alternatives beyond those.

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 read-only, open-world, idempotent. Description adds that each call cascades through several lookups internally, replacing 2-3 manual steps, providing useful behavioral context beyond annotations.

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

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

Dense but efficient paragraph with examples and usage. Could be slightly more structured (e.g., bullet points) for faster scanning, but no wasted 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 no output schema, description fully covers inputs, outputs per type, internal behavior, and usage context. Completes the picture for a tool that resolves two entity types with different data.

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, description adds significant meaning: explains return values per type (ticker+CIK+name for company, RxCUI+ingredient+brand for drug) and clarifies inputs for 'value' field, enabling 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?

Description clearly states the tool resolves names to canonical IDs, with specific examples like 'What's the ticker for...' and differentiates from siblings (e.g., entity_profile) by focusing on ID lookup.

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

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

Explicit guidance 'Use FIRST whenever you have a name but need an ID.' Covers when to use for each entity type and accepted inputs. No explicit when-not, but alternatives are implied by 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 declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds valuable behavioral context beyond annotations: it explains that the tool probes each entity with 'ai_visibility_check', ranks by score, and returns a ranked list with score, confidence, and signal density. 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 three sentences long: the first states the core action and outcome, the second provides context and an example, and the third describes the return format. It is front-loaded, concise, and contains no unnecessary words.

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

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

Given the absence of an output schema, the description fully explains what is returned (ranked list with score, confidence, signal density per entity). It also covers the probe mechanism and the role of the 'context' parameter. The tool is complex with multiple parameters, and the description provides sufficient context for correct usage.

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

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

Schema coverage is 100%, so the description does not need to repeat parameter details. However, it adds extra semantics by explaining that the first entity is treated as the 'subject' for narrative and the rest as competitors, which is not in the schema descriptions. This enhances understanding beyond the schema.

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

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

The description uses specific verbs like 'compare', 'probe', and 'rank' to clearly state the tool's function of comparing AI visibility across multiple entities. It explicitly distinguishes from sibling tools by building on 'ai_visibility_check' and offering a multi-entity comparison, which is not done by other 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?

The description provides a clear use case ('competitive AI-marketing audits') and an example question, indicating when to use the tool. It does not explicitly state when not to use it or mention alternatives, but the context and reference to sibling tools imply appropriate usage.

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

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

Annotations already indicate read-only, idempotent, non-destructive. The description adds crucial behavioral details: partial failures degrade gracefully, bundlephobia's first measurement can take 5-30s, and sources_failed lists timeouts. 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 purpose, then usage, then details. Every sentence is meaningful, no wasted words. Appropriately sized for the complexity of a multi-source composite tool.

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

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

With no output schema, the description fully explains the return structure (summary block, advisories, links, alternatives) and handles edge cases like partial failures. It covers all necessary 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 both parameters described. The description adds that version defaults to latest and accepts scoped packages, providing minor value beyond schema. Baseline 3, boosted for clear guidance.

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

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

The description clearly states it performs a composite npm package check using deps.dev and bundlephobia. The verb 'scan' and resource 'dependency' are specific, and the tool is unique among siblings with no similar ones.

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

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

Explicitly tells when to use: when an agent asks about safety/popularity/size or cost of adding a package. Also notes limitations (npm only, v1) and directs to deps.dev:version for other ecosystems, providing clear alternatives.

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

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

Beyond annotations (readOnly, idempotent), description reveals engine details (BGE-base-en, cosine, 500-char windows), 200K cap with truncation, and offset return for verification. 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?

Each sentence earns its place: purpose, usage, pairing, technical detail, cap, output. No redundancy; front-loaded with core action.

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

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

Despite no output schema, description explains return values (top-N passages with offsets and similarity). Covers all aspects for a 3-param semantic search tool.

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

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

Schema coverage is 100%, and description adds context: text max chars, query examples, limit range 1-20 default 5. Provides meaning 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 'Semantic search INSIDE a fetched record' with concrete examples (SEC 10-K, article) and distinguishes from siblings like ask_pipeworx_grounded and deep_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?

Explicitly says 'Use when the record is too big to cram into the prompt' and suggests pairing with ask_pipeworx_grounded, providing clear when-to-use and alternative 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?

Adds context beyond annotations: describes mutating subscription creation, authentication needs, return value (new id), and delivery channel behaviors. No contradiction with annotations (openWorldHint, idempotentHint).

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

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

Well-structured with front-loaded purpose, then systematic coverage of types and delivery. Slightly long but each sentence adds value. Could be more concise but effective.

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

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

Comprehensive for a subscription creation tool: covers purpose, requirements, types, parameters, delivery channels, constraints, and return value. No output schema needed; description 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?

Adds significant meaning beyond schema: explains each type's params object with examples (e.g., sec_8k with items codes), and details delivery object including SMS cap and webhook signing process. Schema coverage is 100%, so baseline is 3, but description elevates it.

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

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

Specific verb 'Create' + resource 'proactive monitoring subscription' clearly states purpose. Distinguishes from siblings like list_subscriptions, unsubscribe, and recent_alerts by focusing on creation of new 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?

Explicitly states requirement for Pipeworx OAuth account, list of supported types with parameter examples, and delivery channel constraints (SMS cap, webhook auto-disable). Does not explicitly mention when not to use, but context is clear.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, confirming safe, non-destructive, and open behavior. The description adds value by detailing the output format (category-bucketed examples with exact tool shapes) and the dynamic nature (drawn from a live catalog), which goes beyond annotations.

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

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

The description is front-loaded with common trigger questions, making it easy for agents to match. It packs much information into one paragraph without redundancy, though it could be slightly more structured (e.g., separate usage and output sections).

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 onboarding tool with one optional parameter, rich annotations, and no output schema, the description fully covers what the tool does, when to use it, how to invoke it, and what to expect from the output (categories and tool shapes). Addresses all key aspects.

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 optional parameter `topic` well described (list of focus areas and default behavior). The description reinforces this but does not add significant new meaning. Baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose as an onboarding entry point for discovering Pipeworx's capabilities, using specific verbs like 'returns category-bucketed example questions' and referencing the 'live catalog of thousands of tools.' It distinguishes itself from sibling tools (e.g., ask_pipeworx, entity_profile) by being the initial discovery tool.

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

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

Explicitly states when to use: 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' Provides guidance on arguments: 'Call with no arguments for the full spread, or pass `topic` to focus.' Lacks explicit when-not-to-use, but the context makes it clear.

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

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

Discloses that the row is deactivated (not deleted) and historical events remain available, adding behavioral context beyond annotations (readOnlyHint=false, destructiveHint=false).

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 succinct sentences, front-loaded with core action, 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 parameter and no output schema, the description fully covers purpose, constraints, and side effects.

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

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

Schema coverage is 100% with one well-described parameter. Description adds link to subscribe but minimal new semantic meaning 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 action 'Cancel a subscription by id,' with a specific verb and resource. It distinguishes from sibling tools like subscribe and list_subscriptions.

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

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

Explicitly mentions ownership enforcement ('you can only cancel your own subscriptions'), guiding use. Lacks explicit when-not-to-use or alternatives, but context is clear.

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

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

Annotations already declare readOnly, openWorld, idempotent, non-destructive. The description adds crucial context: domain (company-financial for US public companies), data sources (SEC EDGAR + XBRL), return format (verdict types with citation and delta), and scope limits. No contradiction with annotations.

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

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

Every sentence earns its place: opening with trigger phrases, then usage guidance, then domain and source details, then return structure and efficiency benefit. No fluff, well-organized.

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 single parameter and lack of output schema, the description fully addresses what the tool does, when to use it, what it returns, and its limitations (v1 supports only company-financial claims). An agent can confidently invoke and interpret results.

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

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

Schema covers the single parameter 'claim' with 100% description. The description adds value by explaining the natural-language nature and providing example claims, going beyond the schema's generic description.

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

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

The description clearly states the verb (validate/verify) and resource (natural-language claim) with concrete examples like 'Is it true that...' and 'fact check'. It distinguishes the tool from siblings by noting it replaces 4-6 sequential calls, making its unique value explicit.

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 advises use when the agent needs to check factual correctness of a claim, and provides examples of supported query types. It does not explicitly state exclusions or alternatives, but the context is clear enough for an agent to decide.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description does not contradict these and adds that the tool returns 'shaped tender plus supporting detail'. It does not disclose rate limits, authentication requirements, or error behaviors, but given the annotations, this is adequate.

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

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

The description is two sentences: the first clearly states purpose and output; the second provides a usage hint with an example. No redundancy or unnecessary detail. It is front-loaded with the most important 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 the tool's simplicity (one required parameter, no output schema), the description fully explains the purpose, what is returned (listing components), and how to obtain the needed input. It is complete for an agent to select and invoke the tool correctly.

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

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

The schema covers the single parameter ocid with a clear description. The description adds value by explaining where to obtain the ocid value (from za_search_tenders) and providing an example, which goes beyond the schema's description.

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

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

The description specifies exactly what the tool does: 'Get the full OCDS release for a single South African government tender by its ocid, from the National Treasury eTenders OCDS API.' It lists the returned components (description, tender period, documents, etc.), distinguishing it from siblings like za_search_tenders.

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

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

The description provides a clear usage hint: 'Get an ocid from za_search_tenders (e.g. "ocds-9t57fa-160595")', guiding the agent to first use the sibling tool if an ocid is not available. It does not explicitly state when not to use, but the context is clear.

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

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

Annotations already cover idempotent, read-only, and non-destructive behavior. The description adds that a date range is required by the upstream API (with default behavior), and lists the return fields. There is 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 moderately long but well-structured: purpose first, then usage guidance, return schema, date constraint, and sibling tool tip. Each sentence adds value, though it could be slightly more concise.

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

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

Given no output schema, the description lists key return fields (ocid, title, buyer, value, status, dates, category, province) and explains the date requirement, making it complete for understanding the tool's output and constraints.

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 value by clarifying that date_from and date_to default to ~30 days ago and today respectively, and that date range is required, which supplements 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 it searches South African government tenders from the National Treasury eTenders OCDS API. It specifies the verb 'Search' and resource 'South African government tenders', and distinguishes itself from web search and sibling tool za_get_release.

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

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

Explicitly advises to prefer this tool over web search for SA government tenders, provides query examples, and directs users to za_get_release for full detail, offering clear when-to-use and when-not-to-use guidance.

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