Spdx License

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds valuable context: default model (Workers AI Llama), free vs. BYO key model for Anthropic, and return structure (per-model score, confidence, signals, raw_response + combined view). No contradictions with annotations.

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

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

Three sentences, front-loaded with main action, each sentence adds unique value. 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?

Despite 4 parameters and no output schema, the description fully explains purpose, parameters, usage conditions, and return format. It covers all necessary context for correct invocation.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds meaning by clarifying default model behavior (free), when _apiKey is needed, and how context helps disambiguate. It also explains the interaction between models and _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 the verb 'probe', the resource 'LLMs for what they know about a business/brand/product/topic', and the output 'score visibility (0-100) per model'. It distinguishes from sibling tools like ask_pipeworx and entity_profile by focusing on multi-model visibility scoring.

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

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

The description provides explicit use cases ('AI-marketing audits, pre-launch brand checks, competitive monitoring') and explains when to provide _apiKey versus default free model. However, it does not explicitly state when not to use the tool or compare to sibling alternatives.

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

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

Annotations already indicate readOnly, openWorld, idempotent, non-destructive. Description adds significant behavioral detail: routes to 3,892 tools, fills arguments, returns structured answers with citation URIs. No contradiction.

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

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

Description is moderately long but front-loaded with key guidance ('PREFER OVER WEB SEARCH'). Every sentence adds value (sources, query types, examples). Minor redundancy in listing aliases could be trimmed.

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

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

Given the tool's complexity (meta-routing across thousands of sources), description covers purpose, usage guidance, behavioral traits, and expected output ('structured answer with citations'). No output schema needed as return value is described.

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

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

Schema has 100% coverage for the single effective parameter (with aliases). Description doesn't add extra semantic meaning beyond what's in the schema. Baseline of 3 is appropriate.

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

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

The description clearly states the tool routes questions to a vast set of authoritative sources (SEC, FDA, etc.), returning structured answers with citations. It uses specific verbs like 'routes' and 'returns', and distinguishes from web search by recommending preference over it. Examples solidify 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?

Explicitly says 'PREFER OVER WEB SEARCH' and lists query types ('what is', 'look up', etc.) and example questions. While it doesn't list when not to use, positive guidance is strong and context-aware.

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 discloses behavioral traits beyond annotations: it explains the 'Hallucination-resistant' mechanism, states that it extracts answers from tool results only, provides explicit refusal reasons, and describes the return structure. Annotations already indicate readonly and idempotent, but the description adds rich context without contradiction.

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

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

The description is moderately long but front-loaded with key purpose and usage. It is well-structured with return format details. While it could be slightly more concise, every sentence contributes to understanding the tool's behavior.

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

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

Given the tool's complexity (routing, extraction, refusal modes, output format), the description is comprehensive. It covers what it does, when to use, how it behaves, and the return structure. Despite no output schema, the description provides enough detail for correct invocation and interpretation.

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

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

Schema description coverage is 100%, so baseline is 3. The description mentions aliases for the question parameter, but this is already documented in the schema. It does not add substantial new meaning beyond what the input 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 the tool's purpose as a 'Hallucination-resistant answer mode for high-stakes reads.' It explains that it routes like ask_pipeworx but extracts the answer using only the tool result, and contrasts it with ask_pipeworx for casual lookups. This distinguishes it from siblings and provides specific verb-resource-usage context.

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

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

The description explicitly says 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts' and provides example scenarios. It also advises 'prefer ask_pipeworx for casual lookups,' giving clear guidance on when to use this tool versus alternatives.

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

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

Beyond annotations (readOnlyHint, idempotentHint), the description adds extensive behavioral context: safety mechanisms (low-confidence short-circuit, closed market handling, wide-spread illiquidity), resolution-rule risk, and instructions to inspect market_match_confidence. 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 verbose, covering many details in paragraphs. While front-loaded with the main goal, it could be more structured or concise. Every sentence earns its place given the tool's complexity, but overall length reduces conciseness.

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

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

Given the tool's complexity and lack of output schema, the description is remarkably complete. It covers input types, processing logic, fan-out examples, response shapes, safety edge cases, and resolution rules. An agent has nearly all necessary context.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds some context (market input types, depth behavior, include_raw summary) but does not significantly extend the schema's own parameter descriptions.

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

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

The description clearly states the tool researches a Polymarket bet by pulling Pipeworx data, resolves, classifies, fans out, and returns evidence. It is specific and uses strong verbs, but does not differentiate from sibling tools like polymarket_edges or polymarket_arbitrage.

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

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

Provides explicit use cases ('should I bet on X', 'what does the data say') and examples of fan-out per category. However, it does not explicitly state when not to use this tool or mention alternatives.

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

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

The description states it returns data sorted by primary metric, includes paired data and citation URIs, and explains handling of off-calendar fiscal years. Annotations indicate readOnly, openWorld, idempotent, and non-destructive behavior, which the description aligns with and supplements. 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 long but every sentence adds value. It is front-loaded with common query phrases. Minor redundancy in listing example phrases, but overall well-structured and efficient for the amount of information conveyed.

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

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

Given only 2 parameters, rich annotations, and no output schema, the description explains the return format (paired data + citation URIs), sorting behavior, and data sources. It covers purpose, usage, parameters, and expected output comprehensively.

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 on both parameters. The description adds significant meaning: explains what data type='company' pulls (revenue, net income, cash, debt) and type='drug' pulls (adverse-event counts, FDA approvals, trials). Also clarifies that values are tickers/CIKs for companies and drug names for drugs.

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

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

The description starts with common comparison phrases and clearly states it provides side-by-side comparison of 2-5 companies or drugs in one parallel call. It distinguishes from sequential single-pack lookups and specifies data sources (SEC EDGAR for companies, FAERS for drugs). The verb 'compare' and resource 'entities' are explicit.

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

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

The description explicitly says 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.' It provides clear context for when to use (comparisons, head-to-head, ranking) and implies not to use for single entity lookups, which are covered by sibling tools like entity_profile.

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

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

Annotations already indicate read-only, open-world, idempotent, non-destructive behavior. The description adds significant behavioral context: it decomposes questions into facets, routes to 3,896 tools in parallel, returns a findings packet with gaps[], and takes 15-60s. 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 relatively long but every sentence adds essential information (account requirement, limitation, use cases, process, return format). It is front-loaded with critical setup info. Could be slightly more structured but remains informative without waste.

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

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

Given no output schema, the description fully explains the return format: findings packet with verbatim evidence, confidence, source, fetched_at, and stable citation. It also covers account tiers, timing expectations, and when results may be empty. This is complete for a complex tool.

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

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

Schema coverage is 100%, but the description enhances understanding: explains that 'depth' controls the number of facets researched (quick=3, standard=5, thorough=8) and that 'question' should be natural language and can be broad/multi-part. This adds practical value beyond the schema's simple descriptions.

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

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

The description clearly states it performs 'grounded multi-source research' across structured data sources, decomposing questions into facets and returning detailed findings. It distinguishes itself from siblings like ask_pipeworx, which is for single lookups, and mentions specific use cases like comparing entities.

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

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

Explicitly provides when-to-use (broad/multi-part questions over structured data) and when-not-to-use (breaking news, colloquial current-news), with clear alternatives (ask_pipeworx). Also notes account requirements and that 'thorough' depth requires a paid plan.

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

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

Annotations indicate read-only, idempotent, non-destructive. The description adds that it returns top-N tools with full schemas and examples, ready to call without a second lookup. This goes beyond annotations by detailing the output format and usage pattern, with no contradictions.

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

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

The description is concise, front-loads the primary purpose, and uses bullet-style listing of domains. Every sentence is informative with no redundancy. The structure logically flows from purpose to usage to output.

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

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

For a discovery tool with 6 parameters (all described) and no output schema, the description fully covers input (aliases, example queries) and output (top-N tools with schemas and examples). It also provides domain context, making it complete for the tool's complexity.

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

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

Schema coverage is 100%, so each parameter is documented. The description adds value by providing natural language examples and listing domain keywords, which helps the agent formulate queries. It also clarifies multiple aliases for the query parameter. While the schema is sufficient, the extra guidance elevates it above baseline.

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

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

The description clearly states the tool discovers tools by describing a task or data, lists specific domains (SEC filings, FDA drugs, etc.), and explicitly differentiates from siblings like 'search' by focusing on tool discovery rather than data search. The instruction 'Call this FIRST' further clarifies its role.

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 when to use (browse/search/discover tools for listed domains) and when to use it first ('Call this FIRST...'), providing clear context and implied exclusion for when a specific tool is already known. It does not mention alternatives directly but sufficiently indicates its primary role.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds behavioral insight about the USPTO PatentsView API sunset May 2025 and that it soft-fails, and emphasizes that it fans out across multiple sources in one parallel call. No contradiction with annotations.

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

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

The description is relatively long but well-structured. It opens with typical query phrases, then explains the tool's purpose and output. Every sentence adds value, though it could be slightly more compact. Still highly effective.

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

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

Given no output schema, the description thoroughly explains return data: cik, company_name, recent_filings (up to 5 with URIs), fundamentals (latest 10-K revenues, net income, cash sorted), patents (with caveat), news, LEI. It is complete for a holistic profile 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% (all parameters described). The description adds meaning by explaining that 'type' is currently only 'company', 'value' can be ticker or zero-padded CIK, and that names are not supported, which goes beyond the schema's enum and type descriptions.

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

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

The description explicitly states 'full cross-source profile of a US public company in ONE parallel call' and lists specific sources (SEC EDGAR, XBRL, USPTO, news, GLEIF) and return fields. It distinguishes from siblings by advising 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view'.

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

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

The description gives clear when-to-use context: 'when the user asks for a holistic view' and explicitly states when not to use: 'names not supported (use resolve_entity first if you only have a name)'. It also provides usage examples like 'Tell me about X'.

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 destructiveHint=true and idempotentHint=true, so the description's mention of deletion adds minimal extra insight. No contradiction, but limited behavioral context beyond annotations.

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

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

Two sentences with no fluff: first states purpose, second provides usage guidance. Every sentence earns its place.

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

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

Given the single required parameter and no output schema, the description fully satisfies the needed context. The schema handles parameter details, and the description covers purpose and usage.

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

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

Schema coverage is 100% with a single parameter 'key' described as 'Memory key to delete'. The description does not add additional parameter details, so baseline score of 3 is appropriate.

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

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

The description states 'Delete a previously stored memory by key,' which is a specific verb and resource. Among siblings like 'remember' and 'recall', it clearly distinguishes itself as the deletion counterpart.

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

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

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

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

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

Annotations already indicate readOnly, idempotent, not destructive. The description adds behavioral details: fetches page, extracts title/description/key links, emits standard markdown format. No contradiction with annotations.

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

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

The description is three sentences: main purpose, process, use cases. No wasted words, front-loaded with essential information.

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

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

With no output schema, the description explains output is a single text blob for site-root/llms.txt. Combined with annotations and schema, the tool is fully specified. Minor gap: not stating if extraction handles dynamic content or just static HTML.

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 repeats default/max for max_links but adds no new meaning beyond the schema. No additional insight on parameters.

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

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

The description clearly states the tool generates a production-ready llms.txt file for any URL, specifying its purpose for AI crawlers. It distinguishes itself from sibling tools like ai_visibility_check and scan_competitor_ai_presence by focusing on llms.txt generation.

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

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

The description provides concrete use cases (getting client's site indexed, drafting for own project, auditing competitor). It does not explicitly state when not to use this tool, but the contexts are clear enough for an agent to decide.

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

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

Annotations already declare read-only, open-world, idempotent, and non-destructive behavior. The description does not contradict nor add behavioral details beyond what annotations provide. For a simple lookup, this is adequate.

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

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

Single sentence with examples, no unnecessary words. Efficiently communicates purpose and parameter semantics.

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?

Tool is simple with one required parameter and an output schema exists (implied by 'has output schema: true'). The description sufficiently covers input; output schema handles return value explanation.

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 0%, but the description clarifies that the `id` parameter expects an SPDX license identifier and provides examples. This adds meaningful context beyond the bare schema type.

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

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

Description clearly states the tool retrieves metadata and descriptors for a specific SPDX license ID, with concrete examples like 'MIT', 'Apache-2.0'. It distinguishes from sibling tool `get_license_text` which likely returns full license text.

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

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

The description implies when to use (for license metadata) but does not explicitly state when not to use or mention alternatives like `get_license_text` or `list_licenses`. Usage context is implied by the tool's purpose.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. Description adds value by specifying the return content ('standard text + cross-references'), which goes beyond the structured annotations.

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

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

Single sentence, front-loaded with key action and scope. Parenthetical adds essential return info. 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?

Given the tool's simplicity (one parameter, output schema exists), the description covers the core inputs and outputs. Could mention error handling for invalid IDs, but overall sufficient for a straightforward retrieval 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?

With 0% schema description coverage, the description must compensate. It adds that the 'id' parameter is an 'SPDX license id', providing context. However, it does not explain valid formats, sources, or potential errors, leaving the agent partially uninformed.

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 'Get', the resource 'full license text', and the specific scope 'for a single SPDX license id'. It distinguishes from siblings like list_licenses and get_license by specifying 'single' and 'SPDX'.

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?

No guidance on when to use this tool versus alternatives (e.g., list_licenses or get_license). Does not state when not to use or any prerequisites.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and non-destructive behavior. The description adds the specific filter options, which is marginal additional behavioral 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 a single, well-structured sentence that front-loads the core purpose and lists filters. 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?

Given the presence of an output schema and the simple nature of listing with optional boolean filters, the description is adequate. It could mention if all licenses are returned or if there is pagination, but openWorldHint may imply complete listing.

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 only 33% (only 'deprecated' has a description). The description lists the filters but does not explain the semantics of each boolean parameter (e.g., what 'osiApproved=true' means). More detail is needed to compensate for low schema coverage.

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

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

The description clearly states the tool lists SPDX licenses with specific optional filters (OSI-approved, FSF Free/Libre, deprecated). It distinguishes itself from siblings like get_license and get_license_text by focusing on listing with filters.

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

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

The description implies usage for filtering licenses but does not provide explicit when-to-use or when-not-to-use guidance, nor does it mention alternatives. The purpose is clear but lacks contextual usage direction.

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

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

Annotations already indicate read-only, idempotent, non-destructive. The description adds that it returns specific fields and only active subscriptions by default, and that inactive can be included via parameter.

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 and return fields, then usage guidance. No wasted words or 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?

Covers purpose, return fields, usage hint, and parameter context. Lacks mention of edge cases (e.g., empty list) or rate limits, but tool is simple and annotations cover safety.

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 does not add new parameter details beyond the schema, but it provides contextual usage for the parameter (active vs inactive).

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 verb 'List' and resource 'subscriptions', with scope 'caller's active'. It clearly distinguishes 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?

It provides clear when-to-use guidance: 'to review what you're monitoring before adding more or to find an id to cancel'. No explicit when-not or alternatives, but context is sufficient.

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

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

Discloses rate limits (5 per identifier per day), free usage, quota exemption, and impact (daily digests affect roadmap). No annotations contradict this information.

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

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

Single paragraph with clear, bullet-like enumeration of use cases. Every sentence serves a purpose—no redundancy, well front-loaded with the core action.

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

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

Given the tool's simplicity and lack of output schema, the description fully covers input expectations, constraints, and impact. No additional context is needed 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%, so baseline is 3. The description adds value by contextualizing the 'type' field with examples and emphasizing tool-focused messages, improving clarity beyond the schema.

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

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

The description uses specific verbs and resources: 'tell the Pipeworx team something is broken, missing, or needs to exist.' It clearly distinguishes this feedback tool from sibling tools that focus on data retrieval or 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?

Explicitly states when to use each feedback type (bug, feature/data_gap, praise) and what not to do ('don't paste the end-user's prompt'), providing 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?

Adds valuable context beyond annotations: data source (CF analytics-engine), no PII, caching (5min-1h). Annotations already declare readOnly, openWorld, idempotent, non-destructive; description complements 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?

Two sentences plus bullet list, no fluff. Front-loaded with core return data. Every sentence serves a purpose.

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

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

Describes return structure adequately (top tools, packs, count) given no output schema. Sufficient for understanding basic output, though explicit format is omitted.

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

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

Schema coverage is 100% with description on 'window'. Description adds value by explaining semantics of different window choices (short vs long term trends).

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

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

Clearly states the tool returns top tools, top packs, and total call volume over a window. Distinguishes from siblings through specific use cases (hot data sources, canonical tool confirmation, alignment check).

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 three explicit use cases for when to use. Lacks explicit 'when not to use' or alternatives, but the context is clear enough for selection.

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

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

Goes far beyond annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint) by detailing conditions like monotonicity checks, partition checks, Jaccard similarity threshold, placeholder filtering, and fill check against live CLOB depth. Discloses failure conditions and trade criteria, with no contradiction to annotations.

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

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

Well-structured with clear sections and bullet points, front-loaded with the key requirement. However, slightly verbose with excessive detail (e.g., exact threshold numbers). Could be tightened while retaining 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?

Thorough description covering inputs, behavior, response fields, and trade conditions for a complex tool with two modes. No output schema, but describes response structure (opportunities[], partition_check, fill_check). Could be more structured in response field listing, but largely 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 parameter descriptions; description adds significant context such as accepting full URLs for event, and explaining that topic triggers cross-event scanning with context retrieval. Provides richer examples and clarifies behavior beyond schema.

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

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

Clearly states the tool finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. Distinguishes two modes (event and topic) with specific examples, and differentiates from sibling tools like polymarket_edges and polymarket_fill_risk.

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

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

Explicitly states requirement of one parameter (event or topic) and what happens if called with no args. Provides clear context for when to use each mode, with examples. Mentions alternative tool for custom sizing. Lacks explicit when-not-to-use scenarios but covers usage well.

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, but the description adds rich behavioral context: caching (1h KV level keyed on knobs), exclusion of Fed bets with reasoning, diagnostics for empty segments, and details on edge calculation (edge_pp_net after slippage, kelly_fraction capped at 0.25, 24h-move warnings). This far exceeds the annotation-only baseline.

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

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

The description is dense but well-structured with clear section headers (MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, CONCENTRATED_LONGSHOT) and logical grouping of response fields. While lengthy, every sentence serves a purpose for a complex tool. It could be slightly more concise, but the organization lowers cognitive load for an AI agent.

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

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

Given no output schema, the description fully documents the response structure: by_segment segments, fed_candidates/fed_note, _diagnostics with funnel counters and filter_skips. It explains why segments might be empty and covers all edge calculations, gate conditions, and knob interactions. This is comprehensive for a tool with 9 parameters and no output schema.

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

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

Schema coverage is 100%, so baseline is 3. The description adds significant value beyond schema descriptions: it explains why min_kelly doesn't filter partitions (partition arbs always return kelly_fraction_half=0) and how min_partition_leg_kelly compensates. It also provides practical context (e.g., slippage_pp note on Polymarket zero fees but bid/ask spread, min_kelly as fraction of bankroll). This enriches parameter understanding considerably.

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 core function: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It specifies that it's for daily discovery ('what should I bet on today') and details three model families (MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, CONCENTRATED_LONGSHOT), distinguishing it clearly from sibling tools like polymarket_arbitrage and polymarket_edge_tracker.

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

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

The description provides a clear use case ('Built for "what should I bet on today" — agents discover opportunities without paging hundreds of markets') and explains filtering knobs (min_liquidity, max_spread_pp, etc.). However, it does not explicitly state when to avoid using this tool in favor of specific siblings, like polymarket_edge_tracker for historical tracking or polymarket_fill_risk for execution analysis.

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

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

The description adds significant behavioral context beyond the annotations, including how snapshots are populated (cache-miss), the structure of returned data (tracked, expired, snapshot_dates), and details on decay calculations. Annotations indicate read-only, idempotent, etc., and description aligns without contradiction.

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

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

The description is well-structured with a clear main statement, Args, RESPONSE, and LIMITS sections. It is somewhat verbose but every sentence adds value. The key question is front-loaded.

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

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

Given no output schema, the description thoroughly explains the response structure (tracked with edge_pp_net time-series, trend, decay, expired with lifespan, snapshot_dates) and includes limitations. It covers all necessary aspects for usage.

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

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

Schema coverage is 100% with both parameters described. The description adds default values, clamp range for 'days', and examples for 'window'. It also explains the purpose of each parameter (lookback, snapshot family), providing useful context beyond the basic 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: 'Edge persistence and decay telemetry' answering 'how long has this edge existed and is it shrinking?'. It distinguishes from siblings implicitly by focusing on time-series analysis of edges, but does not explicitly differentiate from related tools like 'polymarket_edges' or 'polymarket_arbitrage'.

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

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

The description provides context on when to use the tool, such as comparing a fresh wide edge vs. a 3-week-old wide edge. It mentions limits (60-day TTL, daily closes) but does not explicitly state alternatives or when not to use.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint true and destructiveHint false. The description adds rich detail: walks the ladder, returns top-of-book, VWAP fill price, slippage, shares filled, verdict, etc., and warns about forced directional risk — all consistent with safe, read-only behavior.

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

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

The description is thorough but lengthy, with multiple paragraphs and bullet points. It front-loads the purpose but could be more concise; however, the structure with explicit sections ('SINGLE-MARKET:', 'BASKET:') aids readability.

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

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

Given the tool's complexity (two modes, no output schema, 4 parameters), the description comprehensively covers purpose, usage, return values, and warnings, leaving no significant gaps.

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

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

Schema coverage is 100% with descriptions for all 4 parameters. The description adds meaning beyond the schema: explains side defaults and auto-selection in basket mode, and clarifies size_usd interpretation for single-market vs. basket mode.

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 a specific action ('realizable-vs-theoretical edge check against live CLOB order-book depth') and explicitly distinguishes two modes (single-market and basket), differentiating it from sibling tools like polymarket_arbitrage and polymarket_edges.

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

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

Explicitly advises using this tool before acting on polymarket_arbitrage SELL/BUY-EVERY-LEG signals or polymarket_edges trades above ~$500, and warns about the pitfalls of partial basket fills converting arbs into unhedged positions.

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

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

Beyond annotations (readOnlyHint=true), the description details behavioral traits: compatibility_warning conditions, temporal_alignment meaning, and skipped_cross_type/subtype counters. It fully discloses edge cases and result interpretation.

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 into logical sections (TWO MODES, RESPONSE, SAFETY FIELDS) and front-loads the core purpose. While lengthy, every part earns its place; minor redundancy could be trimmed.

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

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

Given no output schema, the description thoroughly covers response structure, safety fields, compatibility conditions, and temporal alignment. It leaves no significant gaps for agent understanding.

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

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

With 100% schema coverage, the description adds value by explaining two modes (topic vs explicit), overriding behavior, and giving concrete examples. It complements schema without redundancy.

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

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

The description explicitly states it computes cross-venue spread between Kalshi and Polymarket for the same resolving question, distinguishing it from siblings like polymarket_arbitrage and polymarket_edges by emphasizing dual-venue and topic matching.

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 (comparing prices across venues) and flags when not (non-equivalent bet shapes via compatibility_warning, temporal alignment issues). It does not explicitly name alternative tools, but it provides clear contextual signals.

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

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

Adds scope info (scoped to identifier) and pairing advice beyond annotations. No contradiction with readOnlyHint etc.

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

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

Three sentences, front-loaded with main action, no wasted words.

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

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

Covers purpose, usage, scope, pairing. No missing info for a simple read-only tool with one optional param.

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%, so baseline 3. Description reiterates key role but doesn't add significant 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?

States specific verb (retrieve/list) and resource (saved values/keys). 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?

Explicitly says when to use (look up context stored earlier) and gives examples (ticker, address, notes). No explicit when-not, but 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?

The description states mark_read:true flags returned events as read, modifying state, but annotations declare readOnlyHint=true, indicating no state modification. This is a clear contradiction, making the description unreliable in combination 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?

Front-loaded with purpose, efficient but includes extra details (alternative endpoint) that could be split out. No wasted sentences, but slightly longer than minimal.

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 5 parameters, no output schema, and annotations, the description thoroughly covers return fields, filtering, side effects, and alternative access. Nothing missing 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?

All parameters have schema descriptions; the tool description adds value by providing usage examples (e.g., 'sec_8k'), explaining mark_read effect, and noting polling compatibility. Minor improvement: could specify that type filters correspond to subscription types.

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 pulls fired events from subscription feed, returns recent alerts with source, citation_uri, and payload. It distinguishes this tool from siblings by focusing on subscription feed alerts.

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 filtering by type and since, explains mark_read behavior, notes that polling works fine, and mentions an alternative endpoint. Lacks explicit exclusions or when-not-to-use guidance.

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

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

Annotations already indicate safe, idempotent, read-only, non-destructive behavior. The description adds valuable context: multi-source fan-out, fallback chain, soft-fail for USPTO, and return structure (changes grouped by source with citation URIs). No contradiction with annotations.

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

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

The description is a single dense paragraph that front-loads example queries. Every sentence adds value, but it is slightly long. Could be more structured, but still 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 (multiple sources, fallback, soft-fail, date parsing), the description covers all critical aspects. It states the return format (changes grouped by source + total_changes + citation URIs) despite no output schema, and clearly differentiates from entity_profile.

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 useful examples for since (e.g., '30d' for typical monitoring) and clarifies value can be ticker or CIK, and type is limited to company. This goes beyond the schema descriptions.

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

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

The description clearly states the tool provides a change feed for a company from SEC, news, and patents within a time window. It uses specific verbs like 'fans out' and distinguishes from the sibling entity_profile tool for static profiles.

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

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

Explicitly provides example queries ('What's new with X', 'latest on Y'), guidance on when to use entity_profile instead, fallback logic from GDELT to GNews, and soft-fail for USPTO. Also explains since parameter formats (ISO date or relative shorthand) with typical values.

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

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

Adds significant context beyond annotations: scoping by identifier, persistence differences (authenticated vs anonymous 24-hour), and pairing with recall/forget. 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?

Four sentences, front-loaded with purpose, then usage, then technical details, then sibling links. 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?

Covers all aspects: purpose, usage, behavioral traits, parameter scoping, and sibling tools. No output schema needed given 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% with clear param descriptions including examples. The tool description does not add extra detail beyond schema, so baseline score of 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 uses a specific verb 'save' and resource 'data' (key-value pair). It clearly distinguishes from sibling tools 'recall' and 'forget' mentioned in the last sentence.

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

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

Provides explicit when-to-use examples like 'discover something worth carrying forward (a resolved ticker, ...)'. Lacks explicit when-not-to-use or alternatives beyond siblings, 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?

Description adds value beyond annotations by detailing internal cascading through multiple endpoints and that it replaces 2-3 manual lookups. Annotations already declare read-only, idempotent, open-world, and non-destructive traits, and description aligns perfectly.

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

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

Description is front-loaded with question examples and structured by type. Slightly verbose in explaining internal behavior but each sentence earns its place. Could be trimmed marginally without loss.

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

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

Given no output schema and complexity of two entity types each with multiple output fields, the description thoroughly documents what each call returns and the internal caching behavior. Complete for agent decision-making.

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

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

Schema coverage is 100%, but description adds significant meaning: explains return values for each type (ticker/CIK/citation for company; RxCUI/brand for drug), input formats accepted, and auto-disambiguation for company. This fully compensates for lack of output schema.

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

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

The description clearly states the tool resolves user-spoken names to canonical identifiers, with specific examples like ticker, CIK, RxCUI. It distinguishes itself from siblings by focusing on ID lookup needed as input for other tools.

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

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

Explicitly says 'Use FIRST whenever you have a name but need an ID.' Provides clear instructions but lacks explicit exclusions or alternatives, though context implies it's the primary lookup tool.

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

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

Annotations indicate safe, idempotent, read-only behavior. The description adds significant behavioral detail beyond annotations: it probes each entity with ai_visibility_check, ranks by score, and surfaces the most/least recognized entity. It also describes the output structure (ranked list with score, confidence, signal density) despite no output schema.

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

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

The description is three sentences long, front-loaded with the core purpose. Every sentence contributes value, but it could be slightly more concise; for instance, 'Probes each entity...' explains the mechanism without unnecessary fluff.

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

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

Given the tool's complexity (4 params, 1 required, no output schema), the description adequately covers the operation, output format, and use case. However, it could briefly explain what 'AI visibility' means or how scores are derived to be fully self-contained, but the provided context is sufficient 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 coverage is 100% with all 4 parameters described. The description adds extra meaning, such as treating the first entity as 'subject' for narrative and clarifying that omitting models uses the default workers-ai. 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 explicitly states the tool compares AI visibility across multiple entities side-by-side, using a specific verb ('Compare') and resource ('AI visibility'). It distinguishes from sibling tools like ai_visibility_check (single entity) and compare_entities (generic comparison) by detailing the internal use of ai_visibility_check and the ranking 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 a clear usage scenario ('competitive AI-marketing audits') with a concrete example ('does Claude know about us as well as our competitors?'). While it doesn't explicitly state when not to use or list alternatives, the context is well-defined for the intended use case.

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

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

The description adds significant behavioral context beyond the annotations: it details that the tool fans out across external services, that bundlephobia's first measurement can take 5-30 seconds, that partial failures degrade gracefully, and that sources_failed will list timed-out sources. This is rich behavioral disclosure.

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

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

The description is long but appropriately detailed for a complex composite tool. It is front-loaded with the core purpose and uses bullet points for return values. While efficient given complexity, it could be slightly trimmed without losing clarity, hence 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?

With no output schema, the description comprehensively lists all return fields: summary block, per-advisory detail, links, and recent alternatives. It also explains partial failure behavior. This provides complete context for an agent to understand what to expect.

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

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

Schema coverage is 100% with both parameters described in the schema. The description adds no new meaning beyond what the schema provides: it confirms that scoped packages are accepted and that version defaults to latest. Baseline score of 3 is appropriate as the description does not enhance parameter understanding beyond the schema.

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

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

The description clearly states the tool as a composite check for npm packages combining deps.dev and bundlephobia data. It explicitly answers the question 'should I add this npm package to my project' and distinguishes itself from sibling tools by specifying the NPM-only scope and the combined data sources.

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

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

The description provides explicit usage guidance: 'Use whenever an agent asks "is X safe / popular / small"...' and mentions NPM ecosystem only in v1, with alternatives for other ecosystems. However, it does not explicitly state when not to use this tool versus alternatives like get_license or compare_entities, though the context is clear.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive behavior. The description adds beyond annotations: it specifies substring matching and case-insensitivity. This provides useful behavioral context without contradicting annotations.

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

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

The description is a single 13-word sentence that is front-loaded with the key action and resources. There is no redundant or unnecessary 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 simplicity of the tool (one param, clear annotations, and an output schema exists), the description provides sufficient information for correct invocation. It could mention pagination or result limits, but these are likely covered by the output schema.

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

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

The input schema has a single parameter 'query' with 0% description coverage. The description compensates by explaining that the query is a substring matched against SPDX id and full license name case-insensitively. This adds meaning beyond the bare 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 action (substring search), the resources (SPDX id and full license name), and a key attribute (case-insensitive). It distinguishes the tool from siblings like get_license or list_licenses by implying it's a broad search function.

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

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

The description does not explicitly mention when to use this tool versus alternatives (e.g., get_license, search_within). While the purpose is clear, there is no guidance on exclusions or preferred usage contexts, which is a gap given the many 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?

Discloses technical details beyond annotations: uses BGE-base-en embeddings, cosine similarity, 500-char overlapping windows, 200K char cap with truncation flag. Annotations already declare read-only and idempotent, and the description adds rich behavioral context without contradiction.

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

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

Six sentences with no wasted words. Front-loaded with purpose, followed by use case, technical details, and pairing advice. Every sentence earns its place.

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

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

Given no output schema, the description explains return format (top-N passages with offsets and similarity scores). Covers cap, truncation, embeddings, and pairing. Complete for a tool of this 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%, so baseline is 3. Description adds value by specifying default for limit (5) and range (1-20), and giving concrete query examples. This enriches the schema beyond just type and description.

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

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

The description clearly states the tool does 'Semantic search INSIDE a fetched record.' It uses a specific verb (search within) and resource (a fetched record), and distinguishes from siblings like 'search' and 'ask_pipeworx_grounded' by mentioning its internal focus and pairing strategy.

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

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

Explicitly advises use when 'the record is too big to cram into the prompt,' explaining the benefit of saving context. Mentions pairing with ask_pipeworx_grounded for grounded answers. While it doesn't list explicit non-use cases, the context is clear and helpful.

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

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

Adds significant context beyond annotations: OAuth requirement, non-persistence for anonymous/BYO, specific type filters, delivery channel details and limits. Annotations indicate idempotentHint=true, which description does not contradict; overall 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?

Well-structured with clear sections: purpose, requirement, types, delivery. Every sentence adds value, no redundancy. Efficiently packs a lot of information without being verbose.

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

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

For a complex subscription creation tool with multiple type-specific params and delivery options, the description is fully comprehensive. Covers all types, their parameters, delivery channels, constraints, and return value. No output schema, but description adequately explains return.

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

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

Schema coverage is 100%, but description greatly enriches each parameter with detailed examples and constraints for each type (e.g., sec_8k items codes, polymarket_edge min_spread_bps, fred_series series_id). Delivery parameters also have clear explanations and validation rules.

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 uses specific verb 'Create' and identifies resource 'proactive monitoring subscription to a live-data event stream', returning the new subscription id. Distinguishes from sibling tools like list_subscriptions and unsubscribe by focusing on creation.

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

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

Explicitly states requirement for Pipeworx OAuth account, explains supported types and delivery channels with clear examples and constraints (e.g., anonymous+BYO cannot persist, SMS 10/day cap). Provides enough context to decide when to use versus alternatives.

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

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

Annotations already declare read-only, open-world, idempotent, and non-destructive traits. The description adds value by explaining that the output is category-bucketed example questions with tool+argument shapes from a live catalog, and details the behavior of the optional topic parameter. No contradictions.

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

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

The description is front-loaded with common questions and uses a clear structure: purpose, output summary, usage guidance. It is slightly long due to the list of categories, but each sentence earns its place.

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

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

Given no output schema, the description fully explains the output format (category-bucketed example questions with tool+argument shape) and covers both the no-argument and topic-argument cases. It also ties into the broader tool ecosystem by mentioning meta-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% for the single optional parameter. The description goes beyond by listing example topic values and explaining that omitting the argument gives a cross-category spread, which adds practical context not in the schema.

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

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

The description states a specific action ('suggest questions') and resource ('Pipeworx capabilities'), and distinguishes itself from siblings by positioning as the onboarding entry point for learning what Pipeworx can do and how to call meta-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 tool first when not knowing what Pipeworx can do or to learn meta-tools, and explains the difference between no argument (full spread) vs. topic focus. It does not provide explicit when-not-to-use instructions but the context is clear.

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

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

The description adds important behavioral context beyond annotations: ownership enforcement, deactivation (not deletion), and preservation of historical events. No contradiction with annotations.

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

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

Two sentences, no fluff. The first sentence states the purpose, the second adds constraints and behavior. Every word earns its place.

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

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

For a single-parameter tool with annotations and no output schema, the description covers purpose, ownership constraint, behavioral details (deactivate vs delete), and impact on historical data. It is 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?

The only parameter 'id' is fully described in the schema ('Subscription id (uuid) returned by subscribe'). The description does not add additional parameter information, so baseline 3 is appropriate given 100% schema coverage.

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

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

The description clearly states 'Cancel a subscription by id,' which is a specific verb+resource combination. It distinguishes itself from siblings like 'subscribe' and 'list_subscriptions'.

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

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

It specifies ownership enforcement ('you can only cancel your own subscriptions') and explains the deactivation behavior. While not explicitly listing alternatives, the context is clear and provides necessary usage constraints.

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, idempotentHint, non-destructive. The description adds rich behavioral details: sources (SEC EDGAR + XBRL), return types (verdict, structured form, actual value with citation, percent delta), and performance benefit (replaces 4-6 calls). No contradictions with annotations.

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

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

The description is front-loaded with usage examples and purpose, then progressively details scope and behavior. While a bit verbose, every sentence adds value; minor reduction 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 no output schema, the description fully covers return value semantics (verdict types, structured form, citation, delta) and limitations (v1, domain). It is complete for a tool with a single parameter and clear behavior.

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

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

Schema description coverage is 100% for the single 'claim' parameter. The description adds meaning by specifying domain constraints ('company-financial claims...') and providing example inputs, which complements the schema well.

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 provides specific verb-resource pairs ('fact check', 'verify the claim') and distinguishes the tool from siblings by stating it handles natural-language claim verification for company-financial claims, replacing multiple sequential calls. It is not a tautology and clearly identifies the domain.

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

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

The description explicitly states 'Use whenever the agent needs to check whether something a user said is factually correct' and notes the current scope ('v1 supports company-financial claims...'). It lacks explicit when-not-to-use or alternative tool references, but the usage context is clear.

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