Brazil Pncp

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

Annotations already indicate read-only, open-world, idempotent, non-destructive behavior. The description adds value by explaining the scoring (0-100), per-model response structure, the default model, and that Anthropic requires a BYO key with direct billing. 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 three concise sentences: first states purpose and output, second covers key parameters, third lists use cases. No unnecessary words, front-loaded with essential information. Excellent structure.

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

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

Given no output schema, the description adequately explains return format (per-model fields + combined view) and use cases. However, it does not elaborate on the meaning of 'signals' or 'confidence' in the output, which could be helpful for an agent. Mostly complete for a read-only probing 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?

All 4 parameters are described in the schema (100% coverage). The description adds extra meaning: it explains that omitting 'models' uses the default, 'context' disambiguates entities, and '_apiKey' is passed through. This goes beyond bare 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 probes LLMs for knowledge about an entity and scores visibility (0-100). It specifies the verb (probe, score) and resource (LLMs, entity). While distinct from siblings like ask_pipeworx (which is for Pipeworx-specific Q&A) and deep_research (general research), it does not explicitly differentiate itself from 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 use cases (AI-marketing audits, pre-launch checks, competitive monitoring) and mentions the default model and optional Anthropic key. However, it lacks guidance on when not to use this tool or explicit alternatives (e.g., deep_research for broader research). Usage context is implied but not comprehensive.

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 that it routes to 4,819 tools, fills arguments, and returns structured answer with citation URIs. This provides context beyond annotations without contradiction.

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

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

The description is front-loaded with the key point 'PREFER OVER WEB SEARCH'. It includes many examples and comparisons, but some repetition of source types could be trimmed. Overall, each sentence is useful and well-structured.

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

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

Given the complexity of the tool (4,819 tools) and rich annotations, the description is complete. It explains what the tool does, when to use it, and what the output looks like (structured answer with citations). No output schema exists, but the description sufficiently covers return value.

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

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

Schema coverage is 100% with descriptions for each alias (question, query, q, etc.). The description does not add additional meaning beyond 'natural language question'. Baseline 3 is appropriate as the schema already documents the parameter.

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

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

The description clearly states the tool routes questions to a large set of tools and returns structured answers. It explicitly distinguishes from sibling tools like ask_pipeworx_grounded and deep_research, and says 'PREFER OVER WEB SEARCH'. The verb 'ask' and resource 'Pipeworx' are specific, and the function is differentiated from other tools.

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

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

The description provides explicit when-to-use: for factual questions about structured data, and when not to use: for hallucination-resistant single answer use ask_pipeworx_grounded, for broad multi-part use deep_research. It says 'START HERE for most questions' and 'step up only when needed'. This is clear guidance with alternatives.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds mechanism details, refusal reasons, and cost. Could mention rate limits or error handling more, but mostly transparent.

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, front-loaded with purpose, then mechanism, return format, usage guidelines, and cost. No redundant sentences.

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

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

No output schema, but description fully specifies return structure and refusal reasons. Covers usage scenarios and cost. Sufficient for 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 each parameter described. Description does not add extra meaning beyond listing aliases, so baseline 3 is appropriate.

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

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

Clearly states it is a hallucination-resistant answer mode for high-stakes reads, explaining it routes to the right tool, extracts answer from tool result, and returns answer with evidence or refusal. Distinguishes from sibling ask_pipeworx by noting extra cost and use case.

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

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

Explicitly states when to use (high-stakes, quoted/cited answers) and when to prefer ask_pipeworx (casual lookups). Provides clear alternatives and context.

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

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

Annotations already declare readOnlyHint, idempotentHint, etc. The description massively extends transparency with details on fan-out examples, response shapes, resolver contract, parent_event extractor, news fields, safety short-circuits, wide-spread markets, and resolution-rule risk. No contradictions with annotations. This is exceptional disclosure.

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

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

The description is long but well-organized with clear sections (classifiers, fan-out examples, response shapes, etc.). It is front-loaded with the main purpose. Every sentence provides necessary detail for a complex tool. Could be slightly more concise, but the length is justified by the tool's capabilities.

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 extensively explains return values (result.market fields, result.analysis with model probability, result.evidence keyed by source, resolver contract with confidence and alternatives, parent_event extractor, news fields with fallback info). It covers all relevant behavioral aspects and edge cases. Completely adequate 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% - all three parameters are described. The description adds extra examples for the market parameter (slug, URL, question text) and clarifies behavior for depth (default thorough) and include_raw (recommended false to keep responses small). This adds value beyond schema, though the schema already does a good job.

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

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

The description clearly states the tool researches a Polymarket bet by pulling Pipeworx data. It specifies acceptable inputs (slug, URL, question text) and outputs (evidence packet + market-vs-model comparison). This distinguishes it from siblings like polymarket_edges, which focus on specific aspects. The purpose is explicit and actionable.

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 provides example use cases ('should I bet on X', etc.) and explains blocking conditions (low_confidence_match, market_closed_or_inactive). It does not directly list alternatives, but the context signals include many sibling tools. The guidance is clear but could be more explicit about when not to use this tool in favor of others.

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

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

Description adds useful behavioral details beyond annotations: default date range, date format, and that dates filter by publication. Consistent with readOnlyHint and other annotations.

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

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

Description is concise, well-structured with purpose first, then fields, then date details. No redundancy.

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

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

Given no output schema, the description fully explains return fields and date behavior. Parameter info and annotations provide complete 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?

All parameters have schema descriptions, and the tool description adds context about date format and default behavior, enhancing understanding beyond the schema.

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

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

The description clearly states it searches Brazilian government contracts from PNCP, covering various agencies and listing return fields. It is specific but could differentiate from the sibling brazil_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?

Provides implicit usage context (default date range of last 30 days) but no explicit guidance on when to use this tool versus alternatives like brazil_search_tenders.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds details on the output fields (PNCP id, value, dates, etc.) and date format, which are beyond the annotations. No contradictions.

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

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

The description is a single, well-structured paragraph that is front-loaded with the purpose and includes all necessary details 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 no output schema, the description thoroughly details the return fields (PNCP id, object, value, modality, agency, dates, link) and behavior of parameters (date defaults, modality codes), making it complete 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%, providing baseline 3. The description adds meaning by explaining date defaults (omit for last 30 days) and modality codes with examples, adding value over 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 explicitly states it searches for Brazilian government tenders from the PNCP portal, with specific details on what is returned and the legal framework. It distinguishes itself from sibling 'brazil_search_contracts' by focusing on 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 states when to use the tool (for open/recently published procurement opportunities) and provides default behaviors for dates and modality. It does not explicitly mention when not to use it or compare with alternatives, 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?

Beyond the annotations (readOnlyHint, openWorldHint, etc.), the description adds important behavioral details: for company type, it pulls latest 10-K data from SEC EDGAR/XBRL with correct fiscal year handling; for drug type, it pulls FAERS adverse-event counts, FDA approval counts, and active trial counts. It also states results are sorted by primary metric, and returns paired data with citation URIs. No contradictions with annotations.

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

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

The description is comprehensive but slightly long. It is front-loaded with example invocations, which is helpful for the AI. Every sentence adds value, but it could be shortened without losing meaning. Still, it is well-structured and efficient.

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

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

Given the tool's complexity (2 entity types, multiple data sources) and the lack of an output schema, the description fully covers input expectations, behavioral constraints, and output format (paired data + citation URIs). The annotations and schema provide additional context, making this a complete description.

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

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

Schema coverage is 100% with descriptions for both parameters. The description adds meaning beyond the schema by specifying that for company, values should be tickers or CIKs (e.g., AAPL), and for drug, values should be names (e.g., ozempic). This enriches the schema definitions, though the schema already has min/max constraints and an enum for type.

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 'side-by-side comparison of 2–5 companies or drugs' and provides common invocation patterns like 'Compare X and Y' or 'X vs Y'. It distinguishes itself from siblings by claiming it 'Replaces 8–15 sequential lookups', making its purpose specific and differentiated.

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 'ALWAYS PREFER over sequential single-pack lookups when comparing entities', providing clear guidance on when to use this tool. It does not explicitly list when not to use, but the context implies single-entity queries should use the sibling tool entity_profile. This is slightly incomplete for a perfect score.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds valuable context: output format (findings packet with evidence, confidence, source, etc.), explicit gaps[], expected latency 15-60s, and that it never invents answers. No contradiction with annotations.

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

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

Description is comprehensive but slightly verbose; however, all information is relevant and well-structured. Critical warnings and alternatives are front-loaded. Every sentence adds value, though it could be tightened.

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

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

Given the tool's complexity (many data sources, parallel tools), the description covers purpose, usage, output format, limitations, and alternatives. No output schema exists, but the output is sufficiently described. Complete and self-contained.

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

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

With 100% schema coverage, the description explains the depth enum values (quick=3, standard=5, thorough=8) and confirms question is natural language and accepts broad/multi-part questions.

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 1259 structured data sources, decomposes questions into facets, and routes to 4,819 tools in parallel. It also distinguishes from siblings like ask_pipeworx and ask_pipeworx_grounded.

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

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

The description explicitly states best for broad/multi-part questions over structured data, and when not to use (breaking news, current events, single lookups). It provides alternatives (ask_pipeworx) and notes account requirements and paid plan restrictions for depth:'thorough'.

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. Description adds that results include full schemas and examples, ready to call directly, and explains alias behavior. 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?

Concise, well-structured sentences that efficiently convey purpose, usage, and output. 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 no output schema, the description adequately explains return content (tools with names, descriptions, schemas, examples). Missing minor details like error handling, but sufficient for a meta-tool.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining alias usage and default/max limit, going beyond the schema descriptions.

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

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

The description clearly states the tool finds tools by describing data or task, listing many domains. It distinguishes itself from siblings by positioning as a first-call meta-tool for browsing the option set.

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 'Use when you need to browse, search, look up, or discover what tools exist for:' and advises 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' Provides clear when-to-use guidance.

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

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

Annotations already declare readOnly, openWorld, idempotent, non-destructive. Description adds rich behavioral detail: fans out across multiple sources, returns specific fields, soft-fail for patents, mentions USPTO sunset. Does not contradict annotations; adds useful context beyond them.

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

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

The description is a single dense paragraph, but it's well-organized with examples, constraints, and a list of return fields. It is front-loaded with query examples. Could be slightly more structured (e.g., bullet points), but it's effective without wasted words.

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

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

No output schema exists, so the description must explain return values. It does so comprehensively, listing each field (cik, company_name, recent_filings, fundamentals, patents, news, LEI) with details like URIs and sorting. Also covers edge cases like USPTO sunset and name handling. Complete for a complex tool.

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

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

Schema coverage is 100% with descriptions for both parameters. The description reinforces that type must be 'company' and value can be ticker or zero-padded CIK, and names are not supported. Adds practical details like zero-padding and reference to resolve_entity, adding value beyond schema.

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

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

The description clearly states the tool provides a 'full cross-source profile of a US public company in ONE parallel call,' listing specific data sources and return fields. It distinguishes itself from chaining single-pack lookups and provides concrete query examples.

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

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

Explicitly says 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' Also advises using resolve_entity if only a name is available, and warns about USPTO sunset. Provides clear when-to-use and when-not-to-use guidance.

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

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

Annotations already convey destructiveHint=true and idempotentHint=true, so the description's 'Delete' statement aligns. It adds minor context about clearing 'sensitive data,' but beyond that, it does not significantly extend what annotations already provide. The description is consistent and not contradictory.

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

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

The description consists of two concise sentences with no filler. The first sentence states the action, the second provides usage guidance. All content is relevant and front-loaded.

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

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

Given the tool's simplicity (1 parameter, no output schema), the description covers purpose and usage adequately. It does not mention return values or error handling, but for a delete operation this is often acceptable. It is sufficiently 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%, with the parameter 'key' described as 'Memory key to delete.' The main description repeats 'by key' without adding new meaning. Baseline score of 3 is appropriate as the schema adequately documents the parameter.

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

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

The description clearly states 'Delete a previously stored memory by key,' specifying the verb (delete), resource (memory), and the identifying parameter (key). It also distinguishes itself from sibling tools 'remember' and 'recall' by mentioning pairing, which reduces ambiguity.

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 scenarios: 'when context is stale, the task is done, or you want to clear sensitive data.' It also suggests pairing with 'remember' and 'recall,' indirectly guiding when not to use (i.e., when needing to store or retrieve). However, it does not explicitly state when to avoid this tool.

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

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

Beyond annotations (readOnlyHint, idempotent, non-destructive), the description explains the process: fetches page, extracts title/description/links, emits markdown. 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?

Two concise sentences with no wasted words. Front-loaded with the key action and output format.

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

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

For a simple tool with clear parameters and no output schema, the description adequately explains what the output is (text blob) and where to place it. Minor gap: no mention of error handling for invalid URLs.

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

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

Schema coverage is 100% with descriptions for both parameters. The description adds marginal value ('max 50 links') already present in schema. Baseline 3 applies.

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 'Generate', the resource 'llms.txt file', and specifies the purpose for AI crawlers. It distinguishes this tool from siblings by focusing on URL-to-file generation.

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. It implies when to use but lacks explicit when-not scenarios.

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

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

Annotations already indicate read-only, idempotent, non-destructive. Description adds return field details and usage context, providing additional value beyond annotations.

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

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

Two sentences, no fluff. Efficiently conveys purpose, return fields, and usage guidance.

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

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

For a simple list tool with one optional parameter, the description adequately covers return values, usage context, and safety profile. No gaps.

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

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

Schema covers 100% of parameters with description for include_inactive. Description does not add extra meaning beyond what the schema already provides.

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

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

Clearly states it lists the caller's active subscriptions and specifies return fields. Distinguishes from sibling tools subscribe/unsubscribe by its listing function.

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: 'before adding more' (to review) or 'to find an id to cancel'. Provides clear context for 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?

The description discloses behavioral traits beyond annotations: rate-limited to 5 per identifier per day, free usage that doesn't count against tool-call quota, and that the team reads digests daily. Annotations are all false (no readOnly, etc.), and the description complements them without contradiction.

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

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

The description is concise (4 sentences) and well-structured, starting with the core purpose, then usage cases, then additional behavioral notes. Every sentence adds value with no redundancy.

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

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

For a simple feedback tool with three parameters and no output schema, the description provides complete context: purpose, when to use, how to phrase feedback, rate limits, quota impact, and roadmap effect. No gaps remain.

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

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

The input schema already provides high-coverage descriptions (100%). The description adds helpful usage constraints for 'message' (be specific, 1-2 sentences, 2000 chars max) and reinforces that 'context' fields are optional. This adds meaningful guidance beyond the schema.

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

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

The description clearly states the tool's purpose: sending feedback (bugs, features, data gaps, praise) to the Pipeworx team. It distinguishes itself from sibling tools, which are query/research tools, by focusing exclusively on feedback.

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

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

The description explicitly lists when to use each feedback type (bug, feature, data_gap, praise) and provides guidance to describe issues in terms of Pipeworx tools/packs, avoiding end-user prompts. It also mentions rate limits and quota impact, offering complete usage context.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds valuable behavioral context: self-aggregating signal derived from CF analytics-engine, no PII, and caching duration (5min-1h). 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 extremely concise: two sentences plus bullet points. Front-loads purpose, then returns, then use cases. Every sentence adds value with no redundancy.

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

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

For a simple read-only tool with one parameter and no output schema, the description covers purpose, usage, behavior, and parameter. Minor gap: 'top tools' and 'top packs' are not defined further, but overall adequate.

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 only parameter 'window' has an enum and schema description, so baseline is 3. The description adds semantic meaning by explaining that shorter windows surface hot trends while longer windows show steady-state demand, which goes beyond the enum values.

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

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

The description clearly states what the tool does: 'What other AI agents are calling on Pipeworx right now' and lists specific returns (top tools, top packs, total call volume). It distinguishes from sibling tools like 'discover_tools' by emphasizing aggregated signal from other AI agents.

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 explicit use cases for when to use this tool, such as discovering hot data sources or confirming canonical tool selection. However, it does not explicitly state when not to use it or mention alternatives, but the use cases are 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 indicate readOnlyHint=true, idempotentHint=true. The description adds extensive behavioral details: monotonicity checks, partition sum checks, fill check using live CLOB depth, realizable_edge_pp threshold, and thin legs detection. No contradiction with annotations.

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

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

Description is lengthy but well-structured: summary first, then details per mode, then advanced features. Every sentence adds value. Could be slightly more concise, but 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 complexity of arbitrage detection with multiple modes and no output schema, the description fully explains the output structure (opportunities[], partition_check, fill_check details) and references related tool for custom sizing. Covers all essential 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 description coverage is 100% with both parameters described. The description adds meaning beyond schema by explaining modes, providing examples, and detailing internal logic like semantic anchor and partition filter. Adds substantial value.

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

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

Description clearly states the tool finds arbitrage opportunities via monotonicity violations and partition-sum checks on Polymarket. It distinguishes from siblings like polymarket_edges and polymarket_fill_risk by specifying its unique arbitrage detection functionality.

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

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

The description explains when to use no args (trending_scan), event mode (recommended for a specific market), and topic mode (cross-event scanning). It provides examples of slugs and seed questions. Lacks explicit when-not scenarios but gives clear context for each mode.

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

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

Annotations already declare readOnlyHint and idempotentHint. The description adds valuable behavioral details: caching (1h at KV level), response structure (by_segment with diagnostics), and filtering logic. This goes beyond annotations and helps the agent understand side effects (e.g., why a segment might be empty). 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 exhaustive but verbose; it runs as a single dense paragraph. While it front-loads the core purpose, the lengthy technical details (model formulas, specific filters) could be organized into bullet points or sections for readability. It earns its sentences but at the cost of conciseness.

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

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

Given the tool's complexity (9 parameters, multiple segments, no output schema), the description is remarkably complete. It explains available response fields (edge_pp_net, kelly_fraction, diagnostics), the caching behavior, and filter knobs. A minor gap: it doesn't explicitly list all fields in each opportunity, but the textual description is sufficient.

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

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

All 9 parameters have schema descriptions (100% coverage), so the baseline is 3. The tool's main description adds some context (e.g., slippage rationale, min_partition_leg_kelly explanation) but mostly repeats or lightly elaborates on schema info. No substantial new meaning beyond the schema.

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

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

The description clearly states the tool's purpose ('Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price') and identifies its primary use case ('what should I bet on today'). While it implies differentiation from siblings through its model-driven approach, it does not explicitly contrast with sibling tools like polymarket_arbitrage, preventing a top score.

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

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

The description provides strong usage context: it's built for discovery without paging hundreds of markets, and it details tradeable-edge knobs (min_liquidity, max_spread_pp) and diagnostic fields. However, it does not explicitly state when not to use this tool or recommend alternatives, which would further aid agent 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 declare read-only, idempotent, and non-destructive. The description adds significant behavioral context: explains response structure (tracked, expired, snapshot_dates), data sources, limitations (60-day TTL, not intraday), and computation details (decay from daily closes).

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

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

Description is front-loaded with a clear one-liner, then details. It is comprehensive but somewhat long; however, every sentence adds value. Could be slightly more concise, but structure is logical.

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

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

Given no output schema, the description fully explains the return structure with fields like tracked, expired, snapshot_dates and their subfields. Also covers limits and data freshness. Complete for a complex tool.

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

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

Schema coverage is 100% with descriptions. The description adds extra context beyond schema: indicates default values and possible values for window (24hr, 1wk, 1mo) not in schema enums. Adds nuance about 'snapshot family' and reinforces lookback range.

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

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

The description clearly states it provides edge persistence and decay telemetry using daily snapshots, answering specific questions about edge age and trend. It distinguishes itself from sibling polymarket_edges by focusing on historical time-series analysis.

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

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

The description explains when to use this tool (to differentiate fresh vs old edges) but does not explicitly mention when not to use it or alternative tools. However, the contrast between 'fresh wide edge' and '3-week-old wide edge' gives clear usage context.

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

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

The description details what the tool returns for both modes (e.g., top_of_book, vwap_fill_price, slippage_pp, verdict, forced_directional_risk) and explains the logic behind the calculations. It adds behavioral context beyond the readOnlyHint, openWorldHint, and idempotentHint annotations by describing risks like thin legs and directional exposure.

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 capitalised mode headers (SINGLE-MARKET, BASKET) and bullet-point-like lists. While verbose, every sentence adds value. Minor reduction for length and some jargon ('capture overround', 'settlement notional') that could be clarified.

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

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

Given the tool's complexity (two modes, detailed outputs) and no output schema, the description thoroughly explains all return fields, including verdict and forced_directional_risk. It covers edge cases (thin books, partial fills) and provides practical 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?

The input schema has 100% coverage with parameter descriptions, but the description adds significant value by explaining default values (size_usd default 1000, clamp 10–1,000,000), mode-specific interpretations of 'side', and mutual exclusivity of 'market' vs 'event'. However, there is a minor contradiction: description says one is required, but schema has 0 required parameters.

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

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

The description clearly states the tool does a 'Realizable-vs-theoretical edge check against live CLOB order-book depth', differentiating two modes (single-market and basket) with specific verbs and resources. It distinguishes itself from sibling tools like polymarket_arbitrage and polymarket_edges by focusing on fill risk assessment.

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

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

The description explicitly states when to use the tool: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. It also explains why it should be used (theoretical overround not capturable, partial fills cause unhedged positions), providing clear alternatives and context.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds significant behavioral context: it details compatibility_warning conditions, temporal_alignment checks, and skipped_* counters. It explains that spreads are meaningful only when bet shapes are equivalent and temporal periods aligned. 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 detailed and front-loaded with the main purpose. While long, each sentence provides necessary information about modes, response, and safety fields. Minor redundancy could be trimmed, but the complexity justifies the length.

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

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

Despite no output schema, the description thoroughly covers return values: leg-by-leg prices, top_spreads_pp, compatibility_warning, temporal_alignment, and skipped counters. It addresses edge cases like non-equivalent bet shapes and temporal misalignment, making it complete for a complex tool.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by listing exact topic values and explaining the override relationship between explicit parameters and topic mode. It does not repeat schema descriptions but provides operational 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 defines the tool as computing cross-venue spread between Kalshi and Polymarket for the same resolving question. It distinguishes itself from sibling tools like polymarket_arbitrage by focusing on two-venue comparison and explains two operational modes. The verb 'spread' and resource specification are precise.

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

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

The description explicitly explains two modes (topic shortcuts and explicit parameters) and warns that most pre-mapped topics return compatibility warnings, guiding users on expected behavior. It does not explicitly list alternative tools for when this tool is inappropriate, but the context of sibling tools and the detailed safety fields provide implicit 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 indicate read-only, idempotent, non-destructive. Description adds scoping detail (anonymous IP, BYO key hash, account ID) and clarifies listing behavior when key omitted. No contradictions.

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

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

Three sentences, front-loaded with core functionality. Every sentence adds 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?

No output schema, so description should explain return format. Mentions retrieving a value and listing keys but not what the response looks like (e.g., string, object). Pairing with siblings is good, but return format is missing.

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, baseline 3. Description adds value by explaining dual behavior (retrieve vs list) and scoping, going beyond schema description.

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

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

Clearly states verb (retrieve/list) and resource (memory saved via remember). Directly distinguishes from siblings remember and forget.

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

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

Provides explicit use case: looking up previously stored context without re-deriving. Mentions scoping and pairing with remember/forget. Does not explicitly state when not to use, but context is sufficient.

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

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

The description discloses that setting mark_read:true flags events as read, implying a side effect. However, the annotation readOnlyHint=true contradicts this behavior, as marking events read is a write operation. This is a clear annotation 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 concise and well-structured, presenting the main purpose first, then details on parameters and behavior, and ending with an alternative access method. Every sentence serves a purpose.

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

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

Given no output schema, the description adequately explains what returned events contain (source, citation_uri, raw payload). It also covers mark_read behavior and alternative access. Missing explicit mention of limit and unread_only, but they are in the schema.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by providing examples for type ('sec_8k'), clarifying ISO timestamp format for since, and explaining the effect of mark_read. It does not redundantly reiterate all schema details.

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

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

The description clearly states the tool pulls fired events from a subscription feed and returns recent alerts. It specifies the verb 'pull' and the resource 'fired events', distinguishing it from sibling tools like list_subscriptions or recent_changes.

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

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

The description explains filtering by type and since, and mentions polling works fine. It also provides an alternative access method via a direct URL for scripts/dashboards. However, it does not explicitly state when to use this tool versus other siblings, though the context is clear.

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

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

The description adds significant behavioral context beyond the annotations: it fans out to multiple sources, uses fallback logic (GDELT to GNews when rate-limited), and has a soft-fail for patents. It also documents the return structure (changes grouped by source, total_changes count, URIs). No contradiction with annotations (all indicate safe, read-only, idempotent, non-destructive).

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

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

The description is somewhat long but well-structured and information-dense. It starts with example queries for quick understanding, then covers sources, parameters, return format, and sibling differentiation. Every sentence is meaningful, though the length could be slightly reduced for maximal conciseness.

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

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

Despite no output schema, the description covers the return structure (changes grouped by source, total_changes count, URIs), parameter formats, fallback logic, and soft-fail cases. Given the tool's complexity (multi-source aggregation with fallbacks), the description provides sufficient information for an agent to use it correctly.

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

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

Schema coverage is 100% and the description enriches each parameter: `since` explains ISO date and relative shorthand with recommendations, `value` specifies ticker or CIK, and `type` is clarified as only 'company' supported. This adds value beyond the schema descriptions.

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

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

The description clearly states the tool provides a change feed for a company over a recent window, with example queries and explicit differentiation from the sibling tool `entity_profile`. It lists the specific sources (SEC EDGAR, GDELT→GNews, USPTO) and what the tool does, 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 explicitly tells when to use this tool (e.g., 'What's new with X', 'latest on Y') and when to use the alternative `entity_profile` instead. It provides detailed parameter guidance, including acceptable formats for `since` and recommended values like '30d' or '1m'. It also explains fallback behavior and soft-fail conditions.

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 write operation, idempotency, and non-destructiveness. The description adds valuable behavioral details beyond annotations: key-value scoping by identifier, persistence duration for authenticated vs anonymous users (24 hours for anonymous). This enriches the agent's understanding of side effects and data retention.

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

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

The description is three sentences, front-loaded with purpose, followed by usage guidance and technical details. Every sentence adds value without unnecessary words. Highly concise and well-structured.

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

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

Given the simple key-value nature with two fully-specified required parameters and no output schema, the description covers all necessary context: how data is stored (key-value pair, scoped by identifier), persistence behavior, and complementary tools. No gaps for the agent to ask about.

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 descriptive parameter names and examples (e.g., 'Memory key (e.g., "subject_property", "target_ticker", "user_preference")'). The description reinforces the key-value concept but does not add significant new semantic information beyond what the schema provides. 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'. It uses specific verbs ('save', 'reuse') and provides concrete examples (ticker, address, preference). It distinguishes itself from sibling tools by explicitly naming recall and forget for retrieval and deletion.

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 tells when to use the tool: 'Use when you discover something worth carrying forward... so you don't have to look it up again'. It also provides guidance on alternatives: 'Pair with recall to retrieve later, forget to delete.' This gives clear context for selection.

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

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

Annotations already indicate safe, read-only behavior. The description adds that the tool cascades through multiple endpoints, returns specific fields (ticker, CIK, RxCUI, etc.), and includes citation URIs. No contradictions with annotations.

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

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

The description is well-structured with front-loaded purpose and clear separation of supported types. It is moderately concise; every sentence adds value.

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

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

Given the tool's complexity (two entity types, multiple input formats, multiple return fields), the description covers essential usage and output. No output schema, but the description explains returns. Could include error examples but overall complete.

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

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

Schema coverage is 100% with descriptions for both parameters. The description goes beyond by providing concrete input examples and expected return values, 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 explicitly states the tool resolves user-spoken names to canonical identifiers, supported by examples like 'What's the ticker for…'. It distinguishes from sibling tools by noting it replaces multiple manual lookups.

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

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

The description gives clear guidance: 'Use FIRST whenever you have a name but need an ID' and lists supported types with input/output details. It does not explicitly state when not to use it, but the context is 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 already declare readOnly, openWorld, idempotent, and non-destructive. The description adds useful behavioral context: the mechanism (probing each entity via ai_visibility_check), the returned fields (score, confidence, signal density), and the narrative treatment of the first entity. 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 two sentences plus a parenthetical example. It is front-loaded with the core action and avoids verbosity. Every sentence adds value.

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

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

Given no output schema, the description explains the return format (ranked list with score, confidence, signal density) and the process (probes each entity). It covers the use case and parameter purposes. Slight gap: exact output structure is not detailed, but the described fields are sufficient.

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

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

Schema coverage is 100%, so the schema already documents each parameter. The description does not add significant new meaning beyond what the schema provides, but it reinforces the purpose of the 'context' parameter and the special role of the first entity. 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 compares AI visibility across multiple entities side-by-side, probes each with ai_visibility_check, and ranks by score. It distinguishes from the sibling 'ai_visibility_check' which is single-entity, and from 'compare_entities' which may have a different focus.

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

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

The description provides a concrete use case (competitive AI-marketing audits) and an example question. It implies when to use this tool over a single-entity check but does not explicitly state when not to use or list alternatives beyond the sibling context.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint. The description adds behavioral traits: fans out to multiple sources, returns specific fields, handles partial failures gracefully, and notes that bundlephobia's first measurement can take 5-30s.

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 but efficiently packed with purpose, output details, caveats, and limitations. Front-loaded with the composite nature. Could benefit from structure (e.g., output fields listed with breaks), but still 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?

No output schema, but description enumerates output fields (summary block, per-advisory detail, links, alternative versions). Also covers failure modes, ecosystem restriction, and timeout behavior. Sufficiently complete for a composite check tool.

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

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

Schema coverage is 100%, so baseline is 3. The description adds only minor context (e.g., scoped packages accepted, defaults to latest) which mostly repeats schema. No significant additional 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 specifies a composite check for adding an npm package, covering multiple aspects (license, advisories, bundle size). It clearly distinguishes from siblings by stating 'NPM ecosystem only' and pointing to deps.dev:version for other ecosystems.

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 ('is X safe / popular / small' or 'what does adding lodash cost me') and when not ('PyPI / Maven / Cargo / Go fall under deps.dev:version directly'). Also mentions partial failure handling and timeout behavior.

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 non-destructive, idempotent, safe reading. The description adds value by disclosing technical behavior: embeddings (BGE-base-en), chunking (500-char overlapping windows), result details (top-N passages with offsets and scores), and a 200K character cap with truncation flag. 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 compact—three to four sentences—with a clear structure: purpose first, usage guidance second, technical details last. Every sentence provides necessary 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?

Given no output schema, the description adequately explains return values (passages with offsets and scores) and constraints (200K cap with truncation). It covers pairing with a sibling. It could be more complete by describing the exact output structure (e.g., JSON fields), but the level of detail is sufficient for an agent to use the tool effectively.

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

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

Schema coverage is 100%, so baseline is 3. The description restates the schema details (text max 200K, limit defaults, query examples) without adding new meaning. It provides context for usage but does not explain parameter formatting or constraints beyond what the schema already gives.

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

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

The description clearly states the tool performs semantic search within a provided text, using verbs like 'search inside' and 'get back passages'. It distinguishes from the sibling ask_pipeworx_grounded by describing the pair workflow, but does not differentiate from other search-related siblings like deep_research or validate_claim.

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 using the tool 'when the record is too big to cram into the prompt', providing a clear usage context. It also mentions pairing with ask_pipeworx_grounded. However, it does not explicitly state when not to use it or list alternatives beyond the one pair.

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

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

The description adds significant behavioral context beyond annotations: requires OAuth account (not anonymous/BYO), details on delivery channels (SMS cap 10/day, webhook auto-disable after 10 failures, webhook secret returned once), and type-specific parameters. No contradiction with annotations (readOnlyHint=false, idempotentHint=true, etc.).

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

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

The description is lengthy but highly informative with clear structure: start with purpose, then account requirement, then supported types with examples, then delivery channels. Every part adds value, though minor redundancy in delivery details could be tightened.

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

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

Given the complexity (3 params, nested objects, multiple types, no output schema), the description is very complete. It covers return value (new subscription id), account requirement, all subscription types with parameter formats, delivery options with constraints, and webhook security details. No gaps identified.

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

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

With 100% schema coverage, the description enriches parameters with concrete examples and constraints for each type (e.g., sec_8k with ticker/items, fred_series with series_id) and delivery options (E.164 format, email validation, webhook HMAC signing). This goes well beyond the schema descriptions.

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

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

The description clearly states the tool's purpose with a specific verb 'Create' and resource 'proactive monitoring subscription to a live-data event stream'. It distinguishes from sibling tools like 'list_subscriptions' and 'unsubscribe' by focusing on creation and listing examples of subscription types.

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

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

The description explains when to use the tool (to subscribe to alerts for specific live-data streams) and prerequisite requirements (Pipeworx OAuth account). It mentions supported subscription types with examples but does not explicitly state when not to use or compare with alternatives beyond sibling tool names.

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

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

Annotations already indicate readOnlyHint, openWorldHint, idempotentHint, etc. The description adds value by explaining that the tool returns example questions with exact tool+argument shapes, which is behavioral context beyond the safety profile. No contradictions.

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

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

The description is a single paragraph that front-loads common user queries and then explains the tool's output and usage. It is not overly long, but could be slightly more concise. Every sentence serves a purpose.

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

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

Despite lacking an output schema, the description thoroughly explains what is returned (category-bucketed example questions with tool shapes), the role of the tool (onboarding), the optional topic parameter, and the first-use context. It leaves no significant gaps.

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

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

The schema covers the single parameter 'topic' with 100% description. The description adds practical usage: 'Omit for a cross-category spread' and lists specific focus areas (finance, pharma, etc.) beyond the schema's short list. This provides meaningful 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's purpose: it is the onboarding entry point that returns category-bucketed example questions with tool call shapes. It distinguishes itself from siblings like 'discover_tools' by explicitly focusing on 'what to ask' and providing concrete example queries.

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

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

The description explicitly says to use this tool 'FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools'. It also explains the optional topic parameter to focus the results. While it does not explicitly state when not to use it, the guidance is clear and actionable.

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

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

Adds value beyond annotations by specifying that the row is deactivated (not deleted) and that ownership is enforced. Annotations declare non-destructive and idempotent, which the description expands upon with practical details.

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

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

Two sentences, no waste. Front-loaded with the action 'Cancel a subscription by id.', followed by essential usage and behavioral details.

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

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

Given the tool's simplicity (1 parameter, no output schema), the description covers action, ownership, side effects, and historical availability. Completely adequate for agent invocation.

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

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

Schema covers 100% of parameter descriptions, and the description adds no additional meaning beyond what the schema provides. Baseline score of 3 is appropriate.

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

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

The description clearly states 'Cancel a subscription by id.' using a specific verb and resource, and it distinguishes this tool from siblings like 'subscribe' and 'list_subscriptions'.

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

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

Provides context on ownership enforcement and deactivation semantics, giving clear guidelines on when to use. Lacks explicit alternatives but implies when not to use (only for own subscriptions).

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and nondestructive nature. The description adds useful behavioral details: returns a verdict with structured output, actual value with citation, and percent delta, and replaces multiple sequential calls. No contradictions with annotations.

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

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

The description is relatively concise but includes a list of quoted phrases in the first sentence which adds slight clutter. It is well-structured with a clear statement of purpose followed by details and return format. Every sentence adds value.

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

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

With only one required parameter and no output schema, the description is sufficiently complete: it explains the input format, the domain, and the output structure (verdict, structured form, actual value, citation, delta). No missing context for effective 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 covers 100% of parameters with a clear description. The tool description adds further context by providing multiple example claim formats and specifying the expected natural-language style, adding value beyond the schema.

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

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

The description uses specific verbs ('verify', 'check') and resources (natural-language claim, authoritative sources) and clearly distinguishes from siblings by noting it replaces 4-6 sequential calls. It provides multiple example phrases to clarify the tool's scope.

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

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

Explicitly states when to use ('whenever the agent needs to check whether something a user said is factually correct') and notes current domain limitations (company-financial claims). Does not explicitly mention when not to use or list alternatives, but the usage intent is clear.

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