Colombia Secop

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

Annotations already declare the tool as readOnly, openWorld, idempotent, and non-destructive. The description adds important behavioral context: the default model is free, Anthropic requires a BYO key with direct billing, and it outlines the return structure (per-model fields + combined view). This goes beyond the annotations without contradicting 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 concise (4 sentences) and front-loaded with the main purpose and outcome. Every sentence adds meaningful information: primary function, default behavior, optional parameters, return format, and use cases. No unnecessary repetition or filler.

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

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

Given the tool has 4 parameters, 1 required, no output schema, and annotations covering safety, the description fully covers the essential aspects: purpose, when to use, parameter behavior, cost implications, and return format. It is complete for an AI agent to select and invoke this tool correctly.

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

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

Schema description coverage is 100% (all 4 parameters described in schema). The description adds value by explaining the interplay between `models` and `_apiKey` (free vs paid), and clarifies the `context` parameter's purpose (disambiguation). This enhances understanding beyond the schema alone.

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

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

The description clearly states the tool probes LLMs for knowledge about an entity and scores visibility (0-100) per model. The verb 'probe' and resource 'LLMs' are specific. However, it does not explicitly differentiate from sibling tools like 'scan_competitor_ai_presence' or 'deep_research', which have overlapping 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 explicitly mentions use cases: 'AI-marketing audits, pre-launch brand checks, competitive monitoring.' It also explains when to use the `_apiKey` parameter to include Anthropic. However, it does not provide explicit exclusions or alternatives to this tool among the siblings.

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 that the tool returns structured answers with stable pipeworx:// citation URIs, works on every tier, and makes 'one fast call'. This provides useful behavioral context beyond the annotations.

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

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

The description is relatively long but well-structured with front-loaded key guidance, examples, and escalation advice. Every sentence adds value, though some redundancy could be trimmed. Competent structure earns a 4.

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

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

Given the tool's complexity (routing across thousands of sources), the description, combined with rich annotations and full schema coverage, provides complete context. It explains what the tool does, when to use it, behavioral quirks, and return format. 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 description coverage is 100%, so the schema already documents the parameters including aliases. The description provides examples of valid questions but does not add significant semantic meaning 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 'routes the question to the right one of 4,773 tools across 1242 verified sources' and gives specific examples. It distinguishes itself from siblings like ask_pipeworx_grounded and deep_research, making the purpose unambiguous.

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

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

Explicitly says 'PREFER OVER WEB SEARCH' and provides concrete when-to-use guidance with examples. It also tells when to step up to alternatives, such as ask_pipeworx_grounded for hallucination-resistant answers or deep_research for broad questions.

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

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

Annotations already indicate readOnly, openWorld, idempotent, non-destructive. Description adds valuable behavioral details: explicit refusal reasons (not_in_source, no_tool_match, etc.), evidence extraction, and the fact that it uses only tool result. No contradictions. High transparency for a grounded tool.

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 dense sentences followed by a structured list of return fields and refusal reasons. Front-loaded with key concept ('hallucination-resistant'). Every sentence provides essential information without redundancy. Highly efficient.

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

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

Given the complexity (4733 tools, 1242 sources) and no output schema, the description adequately covers return format, refusal behavior, and when to use. Could be enhanced with an example question or specific edge-case handling, but sufficient for an agent to understand tool's role.

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

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

Schema coverage is 100% with clear aliases for question. Description does not add new parameter semantics beyond schema, but it does explain the output format indirectly (answer, evidence, etc.) which aids interpretation. Baseline 3 is appropriate as schema carries the burden.

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

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

The description clearly identifies the tool as a hallucination-resistant answer mode for high-stakes reads, contrasting with ask_pipeworx for casual lookups. It specifies the behavior: picks tool, fetches data, extracts answer using only results. Purpose is specific and distinct from siblings.

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

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

Explicitly states when to use: 'whenever an answer will be quoted, cited, or acted on' and when to prefer alternative: 'prefer ask_pipeworx for casual lookups'. Also mentions cost trade-off ('costs one extra LLM call'). Provides clear contextual 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?

The description extensively details behaviors beyond annotations: it explains low-confidence match short-circuiting, closed market handling, parent event extraction, news fallback mechanisms, wide spread warnings, and cancellation rule parsing. Annotations already mark it as read-only/idempotent, but the description adds rich operational context.

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

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

The description is very long but well-structured with sections (CLASSIFIERS, FAN-OUT EXAMPLES, etc.) and front-loaded with the main purpose. However, it could be more concise; many examples and details are provided that could be streamlined.

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

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

Given the tool's complexity (multiple classification categories, fan-out examples, response shapes, edge cases), the description covers all necessary information: input handling, classification, evidence sources, response field explanations, safety mechanisms, and resolution risks. It leaves no major gap.

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

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

Schema coverage is 100% and description adds value: it explains market input can be slug/URL/question, depth enum with default, and include_raw with rationale for when to use true. The examples further clarify usage.

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

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

The description clearly states the tool researches a Polymarket bet by pulling Pipeworx data, resolving the market, classifying the bet, fanning out to data packs, and returning an evidence packet plus comparison. It distinguishes itself from siblings like polymarket_arbitrage and polymarket_edges by focusing on research and evidence gathering.

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: 'should I bet on X', 'what does the data say about Y', 'is there edge in Z'. It also notes when the tool blocks (low-confidence matches, closed markets) but does not explicitly compare to sibling tools beyond the listed use cases.

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 context: returns 'shaped rows' with specific fields, values are in Spanish as published, and full-text matching behavior. No contradiction with annotations.

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

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

The description is very concise, with only a few sentences that front-load the key purpose and preference. Every sentence adds value—no fluff or repetition.

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

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

Given no output schema and 5 parameters, the description covers the purpose, usage context, parameter behavior, and output format. It could benefit from mentioning pagination or rate limits, but overall it's fairly complete for a search tool.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds value beyond the schema by explaining that omitting the query parameter yields most-recent contracts, and that Spanish terms work best. It also reinforces the limit range and provides context for the _apiKey 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 it searches Colombian government awarded contracts from SECOP II, specifies the data source, and provides example use cases. It explicitly distinguishes itself from web search and siblings like colombia_search_processes by saying 'PREFER OVER WEB SEARCH' for specific 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 gives explicit when-to-use guidance ('PREFER OVER WEB SEARCH for...') and explains when to omit the query parameter to get recent contracts. It also notes that Spanish terms work best. While it doesn't explicitly say when not to use, the emphasis on preference 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 declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. Description adds behavior: returns shaped rows with specific fields, values in Spanish, full-text matching, optional API key. 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?

Single paragraph, front-loaded with purpose and usage. Every sentence adds value. Efficiently 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?

No output schema, but description lists return fields. Covers purpose, usage, parameters, return format, and hints. Complete for a 4-param 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 100%. Description adds meaning: explains query matches name/description, omit for recent, entity partial match, _apiKey for rate limits. Provides examples and hints (Spanish terms best).

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

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

The description clearly states the tool searches Colombian government procurement tenders from datos.gov.co, using specific verbs and resource. It distinguishes from web search and implies differentiation from sibling colombia_search_contracts.

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

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

Explicitly states when to prefer this tool over web search (e.g., 'open tenders in Colombia') and when to omit query for most recent. Does not compare to sibling colombia_search_contracts but provides clear context.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false. The description adds valuable behavioral details: it pulls latest 10-K data from SEC EDGAR/XBRL (with correct handling of off-calendar fiscal years), FAERS data for drugs, returns sorted results by primary metric, and provides 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 relatively long but well-structured: starts with example queries, then explains behavior, data sources, and output. Every sentence adds value. It is not overly verbose given the tool's complexity, but it could be slightly more concise without losing clarity.

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

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

Despite lacking an output schema, the description explains the output format (paired data, sorted by primary metric, includes citation URIs). It covers when to use, what data sources to expect, and how results are presented. The tool is complex (two entity types, multiple entities), and the description fully addresses the agent's needs for correct invocation.

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

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

Schema coverage is 100%. The description enriches both parameters: for 'type' it explains the data sources and behavior for each enum value ('company' pulls 10-K data, 'drug' pulls FAERS counts); for 'values' it provides concrete examples (tickers/CIKs for companies, drug names) and constraints (2-5 items). This adds significant 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 function: side-by-side comparison of 2-5 companies or drugs in one parallel call. It provides example queries and specifies the data sources (SEC EDGAR/XBRL for companies, FAERS for drugs). It distinguishes from sequential single-entity lookups, making the purpose unambiguous.

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

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

The description explicitly advises preference over sequential lookups and provides example use cases like 'Compare X and Y', 'which is bigger', 'rank these companies'. It does not explicitly state when not to use, but the context of multi-entity comparison is clear, and the sibling tools include single-entity lookups like 'entity_profile', implying the distinction.

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

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

Annotations already indicate read-only, open-world, idempotent, non-destructive behavior. Description adds substantial behavioral context: parallel decomposition across 4,773 tools, returns verbatim evidence with gaps array, never invents answers, and constraints like account tiers. 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 relatively long but well-structured: critical caveat first (account required), then usage guidance, core purpose, behavioral details, and edge cases. Front-loaded with key info. Slightly verbose, but for a complex tool the structure earns a 4.

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 parameters, no output schema), the description fully covers all necessary context: return format (findings packet with gaps), behavior (parallel decomposition), limitations (not for news, accounts required), and alternatives. Complete 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 both parameters with descriptions. Description adds meaningful context: for 'depth' it specifies the number of facets (quick=3, standard=5, thorough=8) and paid plan requirement for 'thorough'. For 'question' it notes broad/multi-part is fine. Adds value beyond schema.

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

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

The description explicitly states the tool performs grounded multi-source structured research across Pipeworx's 1242 data sources, distinguishing it from open-web search. It uses specific verbs like 'decomposes' and 'routes', and contrasts with sibling tool ask_pipeworx, making its 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?

Provides clear when-to-use criteria: 'Best for broad/multi-part questions' and explicit alternatives: 'For a single lookup use ask_pipeworx' and 'For BREAKING... prefer ask_pipeworx'. Also notes account requirement and expected response time (15-60s).

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 valuable behavioral context: returns top-N relevant tools with schemas and examples, ready to call directly without second lookup. No contradiction.

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

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

The description is front-loaded with purpose and usage. It is slightly long but every sentence adds value. Could be more concise, but not verbose enough to detract significantly.

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

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

Despite no output schema, the description fully explains what is returned: top-N tools with names, descriptions, and full input schemas. Given the tool's complexity (6 params, 1 required), the description is complete and sufficient for an agent to understand and invoke correctly.

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

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

Schema description coverage is 100%, so baseline is 3. The description lists example queries and mentions aliases, but does not add significant meaning beyond the schema. The parameter descriptions in schema are already clear.

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

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

The description clearly states the tool's purpose: 'Find tools by describing the data or task.' It also distinguishes from siblings by advising to call this first when exploring options. The verb 'discover' and resource 'tools' are specific.

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

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

Explicit guidance on when to use: 'Use when you need to browse, search, look up, or discover what tools exist for...' and 'Call this FIRST when you have many tools available and want to see the option set.' This provides clear context for appropriate usage.

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

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

Describes parallel fan-out across multiple sources, soft-fail behavior for patents, and unsupported name input. Annotations indicate read-only, idempotent, non-destructive; description adds operational 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?

Front-loaded with examples, each sentence adds value. Slightly long with detailed source enumeration but still effective.

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

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

Comprehensive: covers input constraints, return fields, limitations, fallback behavior, and cross-references sibling tools.

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

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

Schema coverage is 100%, baseline 3. Description adds value by specifying ticker or zero-padded CIK, giving examples, and noting type enum limited to 'company'.

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

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

Description clearly states it provides a full cross-source profile of a US public company, lists specific return fields (cik, filings, fundamentals, patents, news, LEI), and distinguishes itself from chaining single-pack lookups. It also notes the 'company' type only and name unsupported.

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

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

Explicitly says to use when user asks for a holistic view and to prefer over chaining. Also says to use resolve_entity first if only a name, and notes patents API sunset limitation.

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

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

Annotations already provide destructiveHint=true and idempotentHint=true. The description adds the purpose and context for deletion beyond the annotations, though it does not disclose additional behavioral traits like irreversibility or error handling.

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

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

The description is two sentences: first states the action, second provides usage guidance and sibling references. No fluff.

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

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

For a simple tool with one parameter and no output schema, the description covers purpose, usage context, and sibling pairing. It could mention what happens if the key does not exist, but overall it is 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 input schema has 100% coverage with a clear description for the 'key' parameter. The tool description does not add any extra meaning beyond what the schema already provides, meeting the baseline.

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

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

The description clearly states 'Delete a previously stored memory by key', providing a specific verb and resource. It distinguishes from siblings by mentioning 'Pair with remember and recall'.

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

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

The description gives explicit use cases: 'Use when context is stale, the task is done, or you want to clear sensitive data'. It does not state when not to use, but the positive guidance is clear and mentions sibling tools.

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

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

Rich annotations already provide safety profile (readOnlyHint, idempotentHint). Description adds value: 'Fetches the page, extracts title/description/key links, and emits standard markdown format.' 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?

Three sentences, front-loaded with action, no wasted words. Efficiently conveys purpose, process, and use cases.

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 2 params and no output schema, the description sufficiently explains output format (text blob) and location (site-root/llms.txt). Complete for the tool's simplicity.

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

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

Schema coverage is 100% so description adds no extra parameter meaning beyond name and description. 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 states 'Generate a production-ready llms.txt file' with specific verb and resource. It distinguishes from siblings like ai_visibility_check and scan_competitor_ai_presence by focusing on clean indexing output.

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 cases (client's site indexing, own project drafting, competitor auditing) but does not mention when to avoid or alternatives among siblings.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds return field details but no new behavioral traits beyond annotations. No contradiction.

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

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

Two concise sentences with front-loaded purpose and return fields, followed by usage guidance. 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 low complexity (1 optional param, no output schema), the description covers what is returned and when to use. Could mention default behavior for inactive parameter but is generally 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 a clear description for 'include_inactive'. The tool description does not add extra parameter details but the schema is sufficient.

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 'List', the resource 'subscriptions', and the scope 'caller's active'. It returns specific fields, distinguishing it from sibling tools like 'subscribe' and 'unsubscribe'.

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

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

Provides explicit guidance: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' It implies context for use but doesn't explicitly state when not to use it.

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

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

Description adds behavioral context beyond annotations: rate-limited to 5 per day, free, doesn't count against tool-call quota, and the team reads digests daily. Annotations only indicate non-readonly, non-idempotent, non-destructive; description fills in the full behavioral profile without contradiction.

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

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

Three sentences, front-loaded with purpose, then usage conditions and constraints. Every sentence adds value: what tool does, when to use it, how to write feedback, and rate limits. No fluff.

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

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

Given no output schema, the description covers input usage thoroughly (types, context, message format) and mentions rate limits. However, it omits what the response looks like (e.g., confirmation). For a simple feedback tool, this is nearly complete; a minor gap keeps it from a 5.

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

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

Schema covers all 3 parameters with descriptions (100% coverage). The description reinforces the meaning of 'type' enum and 'message' but adds little beyond what's in the schema. Baseline 3 is appropriate as description does not significantly augment parameter understanding.

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

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

Description clearly states verb 'Tell' and resource 'Pipeworx team', specifies types of feedback (bug, feature/data_gap, praise), and distinguishes from sibling tools by being a direct feedback channel, not a query or action tool. No 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?

Explicitly states when to use for each feedback type (bug, feature/data_gap, praise) and provides a clear instruction to describe issue in terms of tools/packs, not pasting end-user prompts. Also mentions rate limits (5 per identifier per day) and that it's free with no quota impact, giving 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, nondestructive. The description adds valuable behavioral details: 'derived from CF analytics-engine, no PII, just (pack, tool, count), cached 5min-1h depending on window.' 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 well-structured sentences plus a bullet list of use cases. Every sentence adds value, front-loaded with output, then use guidance, then technical details. No wasted words.

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

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

The description explains what is returned (top tools, top packs, total call volume) but lacks explicit structure (e.g., JSON format). While the tool is simple and annotations cover safety, the lack of output schema means a brief note on return format would improve completeness.

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

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

Schema coverage is 100% and the description adds meaningful context: 'Shorter windows surface what's hot right now; longer windows show steady-state demand.' This goes beyond the enum values to guide selection.

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

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

The description clearly states the tool returns 'top tools, top packs, and total call volume' for a recent window, with a specific verb ('returns') and resource ('trending data'). It distinguishes from sibling tools like 'discover_tools' or 'search_within' by focusing on real-time popularity signals.

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 (discovering hot data sources, confirming canonical tools, alignment checking) and explains window choice (shorter vs longer). It lacks explicit 'when not to use' statements, but the context is clear enough for high utility.

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

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

Annotations indicate readOnlyHint true (no writes), openWorldHint true, idempotentHint true, destructiveHint false. The description adds extensive behavioral detail: walks child markets, checks monotonicity, partition check with sum-of-prices ≈1, semantic anchor with Jaccard similarity ≥0.30, partition filter for placeholder slugs, fill check against live CLOB depth. All consistent with annotations and 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 long but well-structured with sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) and clear explanations. While it could be slightly more concise, the detail is justified by the tool's complexity and the need for clear 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 complex tool with multiple modes and checks, the description covers scanning modes, internal logic, edge cases (placeholders, fill check), and response format. No output schema exists, but the description describes the response structure. References sibling tool for custom sizing, making it self-contained and actionable.

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

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

Schema description coverage is 100%, but the description adds significant value beyond: explains what event and topic do in detail with examples, describes the modes, and clarifies that event is recommended. It enriches understanding of parameter usage and behavior.

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

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

The description clearly states the tool finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It differentiates three modes (no args for trending scan, event for specific market, topic for cross-event scan) and distinguishes itself from sibling tools like polymarket_fill_risk.

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

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

Explicit guidance on when to use each mode: no args for trending scan, event for a specific market (recommended), topic for cross-event scanning. It also advises against trading when fill check shows realizable_edge_pp ≤ 0 and references polymarket_fill_risk for custom sizing, providing clear when-to-use and when-not-to-use guidance.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint as true, and destructiveHint as false, indicating a safe, read-only operation. The description goes far beyond these by detailing internal model logic (three segments), edge calculation (net of slippage, Kelly fractions, spread/volume), caching (1h KV-level), and diagnostic fields. No contradictions with annotations exist.

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 structured with clear sections: core purpose, model segments, edge fields, tradeable-edge knobs, and response diagnostics. It is front-loaded with the main value proposition. Despite its length, every sentence adds unique information, and there is no redundancy or unnecessary detail.

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 9 optional parameters, no output schema, and the complexity of this tool (three segments, diverse edge calculation, diagnostics), the description provides comprehensive coverage. It explains what the tool does, how each segment works, what fields are returned, and how parameters control behavior. The only minor omission is the exact JSON structure of the response, but the top-level keys are described sufficiently.

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

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

Schema coverage is 100%, so the schema already documents all 9 parameters. The description adds meaningful context beyond schema descriptions, such as explaining slippage assumptions, Polymarket's fee structure, the rationale behind min_partition_leg_kelly, and tradeable-edge filter behavior. This extra context justifies a score above the baseline of 3.

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

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

The description clearly states the tool's verb+resource: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It targets a specific use case ('what should I bet on today'). However, it does not explicitly differentiate from sibling tools like polymarket_arbitrage or polymarket_edge_tracker, which could overlap in purpose.

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

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

The description implies usage context through phrases like 'Built for 'what should I bet on today'' and 'agents discover opportunities without paging hundreds of markets.' It also mentions Fed bets are included but excluded from ranking, and provides knob guidance. However, it lacks explicit when-to-use or when-not-to-use guidance compared to alternatives, and no exclusions are stated.

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

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

Description provides extensive behavioral details beyond annotations: it explains the response structure (tracked, expired, snapshot_dates), how decay is computed, and data gaps. Annotations already declare readOnlyHint true, and description adds context about snapshot caching and TTL.

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: it starts with a one-line purpose, then details response format, then limitations. Every sentence earns its place; no fluff. It is appropriately sized for the tool's complexity.

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

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

Despite no output schema, the description thoroughly explains the response (tracked[], expired[], snapshot_dates[]) and covers limitations (TTL, gaps). For a complex tool with two parameters and time-series output, this is highly complete.

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

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

Input schema has 100% coverage, describing defaults and clamps. Description adds meaning by explaining 'window' as snapshot family and providing context for 'days' (max 30). This adds value beyond the schema.

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

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

The description clearly states the tool's purpose: providing edge persistence and decay telemetry from daily polymarket_edges snapshots. It uses a specific verb (track) and resource (edges), and distinguishes from sibling tools like polymarket_edges by focusing on historical 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 gives clear context on when to use (to compare fresh vs. old edges) and includes limitations like 60-day TTL. However, it lacks explicit exclusion of alternatives or when-not-to-use scenarios.

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

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

Annotations already declare read-only, idempotent, non-destructive hints. The description adds substantial behavioral context: walks the ladder, returns specific fields (top_of_book, vwap_fill_price, slippage_pp, etc.), and highlights forced directional risk and thin legs. 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 comprehensive but verbose. It front-loads the core purpose, but the detailed mode explanations are lengthy. While every sentence is useful, it could be more concise without losing critical information.

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

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

Given the complexity (two modes, multiple return fields, no output schema), the description adequately covers what the tool returns and the risks. It mentions key outputs like verdict, thin_legs, forced_directional_risk, and profit_usd, making it complete enough for an agent.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining parameter semantics for both modes (e.g., side defaults for basket, size_usd interpretation as settlement notional), and clamps. This exceeds the minimum.

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: realizable-vs-theoretical edge check against live order-book depth. It distinguishes between single-market and basket modes, and explicitly relates it to sibling tools (polymarket_arbitrage, polymarket_edges).

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

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

The description provides explicit when-to-use guidance: before acting on any polymarket_arbitrage signal or edges trade above $500. It also warns about risks like partial fills converting arb into unhedged directional positions, helping the agent decide correctly.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false. The description adds detailed transparency about compatibility warnings, temporal alignment, skipped cross types, and non-equivalent bet shapes. It goes significantly beyond the annotations.

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

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

The description is long but well-structured: purpose, modes, response format, safety fields. It front-loads key information and every sentence adds value. Could be slightly more concise, but remains effective.

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

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

For a complex tool with no output schema, the description covers everything: response structure (leg-by-leg prices, matched spreads), safety fields (compatibility_warning, temporal_alignment, skipped counters), and practical caveats. It is complete for inference.

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

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

Schema coverage is 100% (all 3 parameters documented). The description adds value by listing the exact topic values, providing example tickers/slugs, and explaining the two modes. This exceeds the baseline of 3.

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

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

The description explicitly states the tool computes cross-venue spread between Kalshi and Polymarket for the same resolving question, distinguishes two modes (topic shortcuts and explicit pairing), and explains the output. It clearly differentiates from sibling tools like polymarket_arbitrage by focusing on cross-venue comparison.

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

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

The description explains when to use each mode (topic for pre-mapped macros, explicit for custom pairings) and warns that most pre-mapped topics are not yet tradeable due to compatibility warnings. However, it does not explicitly state when not to use this tool (e.g., single-venue analysis), though the 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?

Annotations already declare readOnlyHint, etc. Description adds value by explaining scoping to identifier and listing behavior when key is omitted.

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

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

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

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

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

For a simple read tool with one optional parameter, description covers behavior, scoping, and pairing with siblings. 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 parameter fully (100% coverage). Description reinforces but doesn't add substantial new meaning beyond schema.

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

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

Description clearly states the verb (retrieve/list) and resource (saved memories), and 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 clear context for use (looking up stored context) and scoping, but lacks explicit when-not-to-use or alternatives among the many siblings.

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

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

Annotations declare readOnlyHint=true, but description says mark_read:true mutates read status, contradicting readOnlyHint. The description adds useful context about persistence and polling, but the contradiction lowers transparency.

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

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

Two sentences, front-loaded with purpose. Some extraneous info about alternative endpoint, but overall efficient.

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

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

No output schema, but description explains return fields. Mentions limit and unread_only only in schema, not description, causing minor gap. Good context on polling and alternative access.

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

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

Schema coverage is 100% (baseline 3). Description adds examples ('sec_8k'), explains mark_read effect, and clarifies 'since' is ISO timestamp, enhancing 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?

Description states clear verb 'Pull' and resource 'fired events from your subscription feed'. It lists key fields returned and filtering options. However, it does not explicitly distinguish from sibling tools like list_subscriptions, though context is clear.

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?

Description provides guidance on filtering (type, since), mark_read behavior, and mentions polling and alternative endpoint. It does not explicitly state when not to use it or compare to alternatives, but context is clear.

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

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

Annotations indicate readOnly, idempotent, openWorld, non-destructive. The description adds valuable behavioral context: parallel fan-out to multiple sources, GDELT→GNews fallback, USPTO soft-fail, and return structure with citation URIs.

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

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

The description is information-dense but well-structured, front-loading with user query examples. It's slightly long but efficient, covering all key aspects without unnecessary repetition.

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

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

The description is comprehensive for a complex tool with multiple sources, parameter formats, and fallback logic. It mentions return structure (changes grouped by source, count, URIs) despite no output schema, but lacks explicit error handling details.

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

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

Schema already describes all parameters (100% coverage). The description enhances with examples for `since` (ISO date, relative shorthand, typical monitoring value) and clarifies that `value` can be ticker or CIK.

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: a 'change feed for a company' that aggregates multiple sources. It provides example queries and explicitly contrasts with sibling `entity_profile` for static data.

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 concrete examples of when to use (e.g., 'What's new with X') and explicitly advises using `entity_profile` instead for static profiles, along with fallback behavior details.

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

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

Annotations indicate idempotentHint=true and destructiveHint=false; the description adds scoping by identifier and retention details (24 hours for anonymous, persistent for authenticated), providing clear behavioral expectations beyond annotations.

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

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

The description is a compact 5-sentence paragraph, front-loaded with the purpose, and every sentence adds distinct value without redundancy.

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

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

Given the simple 2-parameter schema and no output schema, the description covers persistence, scope, use cases, and paired tools, fully addressing 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 descriptions for both parameters. The description adds a naming convention example ('key naming (e.g., subject_property)') but does not significantly enhance understanding beyond the schema.

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

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

The description uses specific verbs ('Save', 'Store') and clearly describes the resource (key-value pair scoped by identifier). It distinguishes itself from sibling tools like 'forget' and 'recall' by explaining the purpose of persisting data across conversations and sessions.

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

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

Explicitly states when to use ('when you discover something worth carrying forward'), notes pairing with 'recall' and 'forget', and provides context on persistence (authenticated vs anonymous sessions).

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

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

Annotations already indicate readOnly, idempotent, openWorld, non-destructive. Description adds value by detailing internal cascading through multiple endpoints, specific return fields for each type (ticker, CIK, RxCUI, etc.), and citation URIs. This goes beyond annotations without contradiction.

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

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

Description is well-structured, starting with concrete example queries to immediately convey purpose. Every sentence adds information, but slightly verbose with the full example list. Still efficient overall.

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

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

Despite lacking an output schema, the description fully compensates by detailing returned fields for each type (ticker, CIK, company name, RxCUI, ingredient, brand) and citation URIs. It also mentions internal cascading, making it completely informative for a two-parameter 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 descriptions cover both parameters 100%, but description adds significant value: example queries, clarification that company accepts ticker, CIK, or name with auto-disambiguation, and drug accepts brand or generic name. This enriches the schema definitions.

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 defines the tool as resolving user-spoken names to canonical identifiers with specific verb 'resolve'. It differentiates from sibling tools by focusing on entity resolution (e.g., ticker, CIK, RxCUI) and explicitly contrasts with other tools like 'entity_profile' which likely uses resolved IDs.

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 FIRST whenever you have a name but need an ID,' giving clear when-to-use guidance. It lists supported types (company, drug) but does not explicitly exclude unsupported types or mention when not to use, though it's implied. The description also notes it replaces multiple manual lookups, adding 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 safe read-only, idempotent, non-destructive behavior. The description adds specific behavioral details: probes each entity with ai_visibility_check, ranks by score, and returns score, confidence, and signal density per entity. This aligns with annotations and provides additional useful context.

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

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

The description is exceptionally concise, consisting of two sentences and an example question. It is front-loaded with the core purpose and includes all essential information without extraneous detail.

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?

Although there is no output schema, the description explicitly states what is returned (ranked list with score, confidence, signal density). It covers parameter behavior, usage context, and output format comprehensively 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 all parameters are described. The description adds semantic value beyond the schema by noting the first entity is treated as the subject for narrative, which guides interpretation of results. Other parameter details are consistent with the schema.

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

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

The description clearly states the tool compares AI visibility across multiple entities side-by-side, ranks them, and identifies most/least recognized. It distinguishes from sibling tools like ai_visibility_check (single entity) and compare_entities (generic comparison) by specifying the exact process and output.

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

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

The description provides clear usage context for competitive AI-marketing audits and an example question. It implies when to use (when comparing multiple entities) versus when to use ai_visibility_check for single entities, but does not explicitly state when not to use it or name 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 idempotentHint and readOnlyHint, but the description adds valuable behavioral context such as the tool 'fans out' across two services, partial failures degrade gracefully, and bundlephobia's first measurement can take 5-30 seconds with a timeout listed in sources_failed. This enriches transparency beyond annotations.

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

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

The description is front-loaded with the primary purpose and is relatively concise given the amount of information. It uses a single sentence with embedded clauses, which is efficient but could benefit from bullet points or clearer structure for scanning. Still, every sentence adds value.

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

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

Despite no output schema, the description comprehensively explains the return format (summary block with fields, per-advisory detail, links, alternative versions). It also covers edge cases like partial failures, version defaults, scoped packages, and performance caveats, making it fully self-contained for agent understanding.

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

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

With 100% schema description coverage, the schema already fully documents both parameters. The description adds meaning by specifying that scoped packages like '@types/node' are accepted for the 'package' parameter and that 'version' defaults to latest when omitted, providing practical usage guidance.

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

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

The description clearly states the tool's action ('composite 'should I add this npm package to my project' check') and resource (npm package), distinguishes itself from sibling tools like deps.dev:version for other ecosystems, and uses specific verbs like 'fans out' and 'returns'.

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 the tool ('whenever an agent asks 'is X safe / popular / small' or 'what does adding lodash cost me'') and provides clear exclusions ('NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly'), guiding correct agent 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?

Discloses behavioral traits beyond annotations: uses BGE-base-en embeddings, cosine similarity over 500-char overlapping windows, 200K char cap with truncation flag, and returns offsets and similarity scores. Annotations already indicate read-only, open-world, idempotent, non-destructive; description adds technical specifics.

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 yet comprehensive: three sentences cover purpose, usage, and technical details. No wasted words, well-organized with front-loaded main action.

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

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

Given no output schema, the description explains the return format (top-N passages with offsets and similarity scores) and mentions truncation flag. Covers input, behavior, and output expectations fully.

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

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

Schema coverage is 100%, but the description adds meaningful context: for text it mentions max chars and purpose, for query it gives examples, and for limit it explains range and default. It also explains the internal windowing and embedding approach, enriching parameter understanding.

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

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

The description clearly defines the tool as semantic search inside a fetched record, with a specific verb 'search within' and resource 'source'. It distinguishes itself from siblings by explicitly mentioning it pairs with 'ask_pipeworx_grounded' and contrasting with fetching entire documents.

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

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

Explicitly states when to use: 'when the record is too big to cram into the prompt' and explains benefits like saving context and returning only relevant passages. Also provides guidance on pairing with another tool for grounding.

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

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

The description adds behavioral context beyond annotations: requires specific auth, delivery channel details, SMS cap, webhook auto-disable. It does not contradict annotations. However, it does not clarify idempotent behavior for re-subscribing, which the annotations hint at.

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

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

The description is front-loaded with the core purpose and structured, but it is somewhat verbose with details like webhook HMAC signing. Every sentence serves a purpose, but a bit of pruning could improve conciseness.

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

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

Given the complexity (3 parameters, nested objects, no output schema), the description is complete: covers auth, return value, types, delivery options, limitations, and special behaviors (webhook auto-disable).

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

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

Schema coverage is 100%, and the description adds significant meaning: explains type-specific parameters with examples, clarifies delivery options, and provides limitations (e.g., phone verification, 10/day cap).

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

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

The description clearly states it creates a proactive monitoring subscription to a live-data event stream and returns a subscription ID. It distinguishes itself from siblings like list_subscriptions and unsubscribe.

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

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

The description explains when to use (proactive monitoring), lists supported types with examples, and mentions prerequisites (Pipeworx OAuth account). It does not explicitly state when not to use, but the context implies it's not for anonymous/BYO users.

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

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

Annotations already provide readOnlyHint, idempotentHint, etc. The description adds behavioral context such as being the onboarding entry point and returning categorized examples with tool shapes. 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 somewhat verbose with multiple example queries upfront, but it is well-structured and informative. Could be slightly more concise without losing meaning.

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

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

Given no output schema, the description explains the return format (categories with example questions and tool shapes) and covers usage. It is complete for a discovery-oriented tool.

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

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

Schema coverage is 100% but the description adds value by giving examples of topic values ('finance', 'pharma') and explaining how to use without arguments vs with topic, which is 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: it returns example questions about what Pipeworx can do, with categories and tool shapes. It distinguishes from sibling tools like 'ask_pipeworx' and 'discover_tools'.

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

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

The description explicitly says to use this first when unsure about Pipeworx's capabilities and mentions using the topic parameter for focus. It doesn't explicitly state when not to use it, but the guidance is clear.

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

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

The description discloses that the row is deactivated (not deleted) and that historical events stay available via 'recent_alerts'. This adds context beyond the annotations, which only indicate non-destructive mutation (destructiveHint=false). 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 two sentences with zero wasted words. It front-loads the purpose and efficiently conveys ownership, effect, and consequence.

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

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

For a simple tool with one parameter and no output schema, the description covers all necessary context: what it does, who can use it, what happens to the data, and how to access historical events.

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 fully describes the 'id' parameter with 100% coverage, including the note that it is returned by 'subscribe'. The description does not add further semantic detail beyond what the schema provides.

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

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

The description clearly states 'Cancel a subscription by id', using a specific verb and resource. It distinguishes from sibling tools like 'subscribe' and 'list_subscriptions' by explicitly mentioning cancellation and ownership enforcement.

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

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

The description provides clear context that ownership is enforced ('you can only cancel your own subscriptions'), implicitly telling the agent when to use this tool. However, it does not explicitly state when not to use it or name alternatives, though the sibling list includes 'list_subscriptions' for finding IDs.

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 discloses the return format (verdict, extracted form, actual value, citation, delta) and replaces multiple calls. Annotations already indicate readOnly, openWorld, idempotent, and non-destructive. No contradictions; adds useful context about SEC EDGAR + XBRL.

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 with trigger phrases and then details. It is reasonably concise, though could be slightly shorter. 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 the return format and domain. It covers what the tool does, its limitations (v1), and the value it provides. Sufficient for the agent to understand its application.

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

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

Schema description coverage is 100% with a clear parametric description. The tool description adds broader context but does not significantly enhance the parameter 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 is for verifying natural-language factual claims against authoritative sources. It provides specific trigger phrases and examples of supported claim types (company-financial). It distinguishes itself from siblings by emphasizing it replaces multiple sequential calls.

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

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

Explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct' and specifies the current scope (company-financial claims for US public companies). Does not mention when not to use or alternative tools, 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.