Flickr Public

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

Annotations already indicate read-only and idempotent behavior. The description adds details about the return format, default vs. paid models, and the BYO key pattern, providing useful context beyond annotations.

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

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

The description is concise (3-4 sentences), front-loaded with the core purpose, and structured to cover purpose, usage, parameters, and output. Every sentence adds value.

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

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

Given no output schema, the description explains the return format. Parameters are fully documented in schema and description. The tool fits well among siblings, but could mention alternatives like 'scan_competitor_ai_presence' for completeness.

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

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

Schema description coverage is 100%, so the schema already explains parameters. The description adds value by explaining the default model, the role of _apiKey, and practical examples for the context 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' and resource 'LLMs for visibility scoring', with a specific output (score 0-100). It distinguishes from siblings like 'ask_pipeworx' by focusing on visibility scoring rather than general Q&A.

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

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

The description mentions use cases ('AI-marketing audits, pre-launch brand checks, competitive monitoring') and explains how to extend with Anthropic, but does not explicitly exclude scenarios or compare with alternative sibling tools.

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

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

Annotations already indicate readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds that the tool routes questions to one of 4,396 tools, fills arguments, and returns structured answers with stable citation URIs. It also states 'one fast call', which is additional context. No contradictions with annotations.

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

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

The description is long but front-loaded with the key preference statement. Every sentence adds information about usage, scope, or differentiation. Slightly verbose but well-organized.

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

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

No output schema exists, but the description explains the return format (structured answer with citation URIs). It covers a wide range of input domains and provides examples. Given the tool's complexity, the description is fairly 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 description coverage is 100%, so baseline is 3. The description elaborates that the main parameter 'question' accepts natural language and lists common query patterns, adding value beyond schema. It also informs about aliases (q, text, etc.), which is helpful for agents.

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: to answer factual questions using authoritative structured data. It specifies the resource ('Pipeworx' suite of tools) and verb ('ask'), and distinguishes itself from siblings like 'ask_pipeworx_grounded' and 'deep_research'.

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

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

The description provides explicit guidance on when to use the tool (e.g., for any factual question, prefer over web search) and when to consider alternatives (e.g., for hallucination-resistant answers use ask_pipeworx_grounded). It includes examples of appropriate queries.

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

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

The description adds substantial behavioral context beyond annotations: it explains the extraction process, the refusal reasons, the exact return structure, and the cost. Annotations already declare readOnly, openWorld, idempotent, and non-destructive, consistent with description.

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

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

The description is a single paragraph that front-loads the key purpose and behavior. Every sentence adds value, covering routing, extraction, return format, usage guidance, and cost. It is slightly long but well-organized.

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

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

Despite no output schema, the description completely specifies the return structure (including success and refusal formats) and the failure reasons. It also explains the cost trade-off, making the tool's behavior fully transparent.

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 aliases documented. The description does not add significant new parameter semantics beyond the schema, but it implies that the question is natural language. Baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose: a hallucination-resistant answer mode for high-stakes reads. It specifies that it uses the same routing as ask_pipeworx but extracts answers only from tool results, distinguishing it from the sibling ask_pipeworx.

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

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

The description explicitly tells when to use this tool (when answers will be quoted, cited, or acted on) and when to prefer the cheaper alternative (ask_pipeworx for casual lookups). It also mentions the cost trade-off of one extra LLM call.

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

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

The description extensively details behavior beyond the annotations (readOnlyHint, idempotentHint, destructiveHint): resolver contract (match confidence, alternatives, suggestions), parent event extractor, news fallback fields, safety short-circuits for low-confidence matches and closed markets, wide-spread illiquidity warnings, and resolution-rule risk. This is far more than annotations provide.

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

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

The description is comprehensive but long (multiple paragraphs). It front-loads the main purpose and then dives into details, which is good. However, it could be more concise by trimming redundant examples or moving some details to a separate section. It earns its length due to complexity, but is slightly verbose.

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

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

No output schema exists, so the description must cover return shape. It thoroughly explains result.market fields (best_bid/best_ask/spread_pp/liquidity/price_change), result.analysis (model_probability/edge_pp/kelly_fraction_half with warning), result.evidence keyed by source, resolver contract, parent_event, news fields with fallback handling, and safety mechanisms. This is 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 baseline is 3. The description adds value by explaining the depth parameter's default behavior ('thorough'), the include_raw parameter's impact on response size, and providing example inputs for market. This goes beyond the schema's enum and string 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 researches a Polymarket bet by pulling Pipeworx data, accepts slugs, URLs, or question text, and returns an evidence packet with comparison. It distinguishes from sibling tools like polymarket_edges and polymarket_arbitrage by focusing on 'research' rather than edge detection or 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 explicitly suggests usage for 'should I bet on X', 'what does the data say about Y', or 'is there edge in Z', and provides examples of fan-out for various bet types. However, it does not explicitly state when not to use it or compare to alternatives like ask_pipeworx_grounded.

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, idempotent, and non-destructive behavior. The description adds the scoping to public uploads and a single group, but does not address pagination, rate limits, or ordering. It relies heavily on annotations for safety transparency.

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

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

The description is a single sentence, which is concise but overly terse. It lacks structural elements that would improve scanability, such as bullet points or explicit parameter context.

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 low complexity, presence of annotations and output schema, the description is minimally complete. However, it omits details like result ordering, error cases, or rate limit information that would help the agent anticipate behavior.

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

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

Schema coverage is 50% (only group_id has a description). The description does not add any details about parameters, such as the meaning of 'limit' or how to format group_id. It fails to compensate for the missing 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 'Public uploads in one group' clearly indicates the tool retrieves uploads scoped to a single group, distinguishing it from siblings like by_user. However, it could be more explicit (e.g., 'List public uploads') and uses 'uploads' as a noun instead of a verb.

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 no guidance on when to use this tool versus alternatives like by_user or search_within. It lacks any context about typical use cases or exclusions.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint as true and destructiveHint as false. The description adds context by clarifying that only public uploads are retrieved, which is consistent with readOnlyHint. It does not contradict annotations.

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

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

The description is a single, concise sentence with no unnecessary words. It is front-loaded and immediately understandable.

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

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

The tool is simple with 2 parameters and an output schema exists, so return values need not be explained. The description covers the essential behavior, though a mention of result ordering or pagination could enhance completeness.

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

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

The input schema has 2 parameters: user_id and limit. Schema coverage is 50% (user_id has description, limit does not). The description only mentions 'from one user', which corresponds to user_id, but adds no detail about limit or formatting. Baseline 3 is appropriate given minimal addition.

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

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

The description 'Public uploads from one user' clearly states the verb (retrieves), resource (uploads), and scope (from one user). It distinguishes from sibling tool 'by_group' which targets group uploads.

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 (get public uploads from a specific user) but does not provide explicit guidance on when not to use or mention alternative tools like search or group retrieval. A brief exclusion or alternative reference would improve clarity.

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: details data sources (SEC EDGAR/XBRL for companies, FAERS for drugs), explains handling of fiscal years, and states results are sorted by primary metric. 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?

Well-structured with query examples upfront, then usage guidance, then data source details. Slightly verbose but each sentence adds value.

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

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

No output schema, but description mentions return format (paired data + citation URIs) and efficiency claims. Adequate for a comparison tool with clear semantics.

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

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

Schema coverage is 100%. Description enriches parameters by explaining what data each type pulls and constraining values to tickers/CIKs or drug names with examples.

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 side-by-side comparison of 2-5 companies or drugs, with explicit example queries like 'compare X and Y'. It distinguishes from siblings like entity_profile which handles single 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 instructs to prefer this tool over sequential single-pack lookups when comparing entities. Gives example queries but does not list specific alternatives beyond that.

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: describes parallel execution, return format (verbatim evidence, confidence, source, fetched_at, citation, gaps[]), response time (15-60s), and behavior for unanswered topics. 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 front-loaded with essential information (account requirement, alternative). Every sentence adds value, and it is well-organized. Slightly verbose but justified by the tool's complexity.

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

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

No output schema, so description fully explains return values: findings packet with evidence, confidence, source, fetched_at, citation, and gaps[]. Also covers behavior for unsupported topics and response time. Complete given the tool's complexity.

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

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

Schema coverage is 100% with both parameters documented. Description enriches by explaining depth enum values (quick=3, standard=5, thorough=8) and indicating broad/multi-part questions are acceptable. Adds meaningful nuance beyond schema alone.

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

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

The description clearly states the tool performs grounded multi-source research across 1102 structured data sources, decomposes questions into facets, and routes to 4,396 tools in parallel. It distinguishes from siblings like ask_pipeworx by specifying it is not open-web search and is for broad/multi-part questions.

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

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

Explicitly states when to use this tool vs alternatives: for single lookups use ask_pipeworx, for breaking/current news prefer ask_pipeworx, and if not signed in use 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 already declare readOnlyHint, idempotentHint, and non-destructive behavior. The description adds value by detailing the return format: 'top-N most relevant tools with names, descriptions, and full input schemas (with curated examples) — each result is ready to call directly.' This provides useful behavioral context beyond the annotations.

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

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

The description is extremely concise: three sentences covering purpose, usage, and return behavior, with no wasted words. It is front-loaded with the core action and efficiently uses space to convey key information.

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

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

Given the tool's simplicity (one required parameter, no output schema, safety covered by annotations), the description provides sufficient context: domains, when to use, output format, and limit. It could mention error handling or relevance sorting, but the limit is covered in the schema. Overall, complete enough for a discovery tool.

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

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

Schema coverage is 100%, so parameters are already fully documented. The description repeats the purpose of the query parameter ('natural language description') and lists example domains, but does not add new semantic constraints or details beyond the schema. Baseline score of 3 is appropriate.

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

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

The description clearly states the tool's purpose: 'Find tools by describing the data or task.' It uses a specific verb ('discover') and resource ('tools'), and distinguishes itself from sibling tools by explicitly saying 'Call this FIRST when you have many tools available and want to see the option set.'

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

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

The description provides explicit when-to-use guidance: 'Use when you need to browse, search, look up, or discover what tools exist for: ...' and advises calling it first when many tools are available. However, it does not mention alternatives or when not to use it, such as when already knowing the 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 already indicate safe read-only, open-world, idempotent, non-destructive behavior. The description adds valuable behavioral context: it 'fans out across SEC EDGAR, XBRL, USPTO, news, GLEIF', notes that 'USPTO PatentsView API sunset May 2025 — soft-fails until reactivated', and explains how fundamentals are returned ('LATEST 10-K Revenues + NetIncomeLoss + Cash, sorted period_end DESC'). No contradictions with annotations.

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

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

The description is relatively long but every sentence is informative. It leads with example queries and a concise summary of what the tool does, then details data sources, return fields, and limitations. While not overly verbose, a more structured format (e.g., bullet points) could improve readability.

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

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

Given the tool's complexity (multiple sources, no output schema), the description is remarkably complete. It explains all return fields (cik, company_name, filings with URIs, fundamentals, patents with sunset note, news, LEI), covers constraints (ticker or zero-padded CIK only), and provides fallback behavior (GDELT→GNews). No critical gaps remain.

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

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

Schema coverage is 100% with descriptions for both parameters (type and value). The description reinforces and expands on the schema: it clarifies that type is limited to 'company', and for value, it provides concrete examples ('AAPL', '0000320193') and reiterates that names are not supported. This adds value beyond the schema.

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

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

The description explicitly states the tool's purpose: providing a full cross-source profile of a US public company. It includes example queries ('TELL ME ABOUT X', 'research Acme'), lists the data sources (SEC EDGAR, XBRL, USPTO, news, GLEIF), and specifies the return fields (cik, company_name, recent_filings, fundamentals, patents, news, LEI). This clearly distinguishes it from sibling tools like resolve_entity.

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

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

The description gives clear guidance on when to use this tool: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also explicitly states when not to use it: 'names not supported (use resolve_entity first if you only have a name).' This provides strong usage context.

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

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

Annotations already indicate destructiveHint=true and idempotentHint=true. The description adds minor context about clearing sensitive data but does not contradict annotations nor provide significant new behavioral 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?

Two concise sentences: first states purpose, second gives usage guidance. No unnecessary text, front-loaded with key 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?

For a simple destructive tool with one required parameter and no output schema, the description sufficiently covers purpose, usage, and pairing with siblings, leaving no gaps.

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

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

Schema description coverage is 100% for the single parameter 'key'. The tool description adds no extra meaning beyond the schema, so baseline score applies.

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

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

The description clearly states the action ('delete') and the resource ('previously stored memory by key'), distinguishing it from sibling tools like 'remember' and 'recall'.

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

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

Explicitly provides when to use ('context is stale, task done, clear sensitive data') and mentions pairing with related tools, offering clear guidance beyond the 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 as true and destructiveHint as false. The description adds behavioral context: it fetches the page, extracts title/description/key links, and emits standard markdown format. No contradictions.

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

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

Three sentences, front-loaded with the primary action, and each sentence adds value (what it does, how it works, why it's useful). No fluff 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?

Given full schema coverage, rich annotations, and no output schema, the description sufficiently explains the output (single text blob, placement at site-root/llms.txt). No missing context for an agent to use the tool correctly.

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

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

Schema description coverage is 100%, so the schema already documents both parameters. The description mentions the URL implicitly and references max_links with defaults, but adds no new meaning beyond the schema.

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

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

The description clearly states the verb ('generate'), resource ('production-ready llms.txt file for any URL'), and context ('AI crawlers... can index the site cleanly'). It distinguishes from sibling tools by specifying the unique output format and use cases.

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

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

The description explicitly lists three use cases: indexing a client's site, drafting for own project, or auditing a competitor. While it does not mention when not to use or alternatives, the context signals from sibling tools like 'scan_competitor_ai_presence' provide implicit differentiation.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds value by specifying the returned fields (id, type, params, etc.) and the default of listing only active subscriptions, which is not evident from annotations alone.

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

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

The description is two sentences, front-loaded with the main purpose, and every sentence adds value. No superfluous 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?

For a simple list tool with one optional parameter and no output schema, the description covers the return fields and provides usage guidance. Slightly improved completeness could include parameter mention, but it's adequate.

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

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

The single parameter 'include_inactive' is fully described in the schema (boolean, default false). The description implies active-only listing but doesn't explicitly reference the parameter. Since schema coverage is 100%, a 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 lists the caller's active subscriptions, specifying the verb 'list' and resource 'subscriptions'. It distinguishes from sibling tools like subscribe and unsubscribe by focusing on listing existing subscriptions.

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

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

The description advises using this tool to review current subscriptions before adding more or to obtain an ID for cancellation. This provides clear context for when to use it, though it doesn't explicitly mention when not to use it or 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 provide minimal behavioral info (all false). The description adds important behavioral details: rate-limited to 5 per identifier per day, free, doesn't count against quota, and the team reads digests daily. This significantly supplements the annotations.

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

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

The description is about 100 words, well-structured with a clear purpose statement followed by usage scenarios and constraints. It is front-loaded with the core action and uses sentence fragments effectively. No unnecessary words.

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

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

Given that the tool has no output schema and is a simple submission, the description is complete. It explains the impact (read daily, affects roadmap) and constraints (rate limit, free). The agent has all necessary information to invoke the tool correctly.

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

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

Schema description coverage is 100%. The description adds context beyond the schema: for 'type', it expands on enum values (e.g., 'bug = something broke...'); for 'message', it provides usage guidance (be specific, 1-2 sentences, 2000 chars max); for 'context', it explains optionality. This adds significant value.

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

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

The description clearly states the action ('Tell the Pipeworx team') and the resource (Pipeworx team). It specifies the purpose: reporting bugs, requesting features, or giving praise. The verb 'tell' and resource 'team' are specific, and no sibling tool handles feedback, so it is well-differentiated.

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

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

The description explicitly lists when to use the tool: for bugs, features/data gaps, or praise. It also provides a negative example ('don't paste the end-user's prompt'). Although it does not explicitly mention when not to use it, the context of sibling tools (none are feedback-related) and the clear positive scenarios make it clear.

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

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

Annotations already declare readOnly, idempotent, and non-destructive. Description adds valuable context: data source (CF analytics-engine), no PII, return shape (pack, tool, count), and caching behavior (5min-1h). 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?

Five sentences, no wasted words. Front-loaded with the verb 'Returns'. Clear, logical flow from what it does to use cases to data source details.

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

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

Given no output schema, description adequately indicates return shape (top tools, top packs, total call volume). Discloses caching. Could benefit from a brief example or note on pagination, but overall sufficient for a simple tool.

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

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

Schema coverage is 100% with a single parameter 'window' and a good description. Description further clarifies the effect of different window lengths: shorter for hot right now, longer for steady-state demand, adding nuance beyond schema.

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

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

Description clearly states the tool returns top tools, top packs, and total call volume over a recent window. It lists three distinct use cases, distinguishing it from siblings like 'discover_tools' or 'recent' by focusing on trending usage data.

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

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

Explicitly describes three use cases (discovering hot data sources, confirming canonical tool, checking alignment). Implicitly suggests when to use this tool over alternatives, though does not directly state when not to use it.

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

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

Annotations (readOnlyHint, openWorldHint, idempotentHint) are consistent. Description adds rich behavioral context: monotonicity violation types, partition check logic, Jaccard similarity threshold, placeholder filtering, fill check against CLOB depth. 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?

Long but well-structured with section labels (REQUIRES, SEMANTIC ANCHOR, etc.). Every sentence provides necessary detail; minor redundancy could be trimmed. Informative but not overly concise.

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

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

Given complex functionality, description covers all aspects: modes, failure reasons, fill check, and response structure. No output schema but describes output fields. References sibling tools appropriately.

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

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

Schema coverage is 100% with descriptions for both parameters. Description adds value beyond schema by explaining modes, example slugs, and acceptance of full URLs. Slight improvement over baseline 3.

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

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

The description clearly states the tool's purpose: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It distinguishes between two modes (event/topic) with concrete examples, and the name and title are consistent.

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

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

Explicit usage guidelines: 'REQUIRES one of event OR topic — call with no args fails.' Recommends event for specific markets, topic for cross-event scanning. Provides when-not to trade via fill check. References sibling tool polymarket_fill_risk for custom sizing.

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

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

Annotations already indicate readOnlyHint true. The description adds caching behavior (1h KV), response structure (by_segment with diagnostics), and per-opportunity fields. 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?

At over 600 words, the description is verbose and includes excessive mathematical detail (e.g., lognormal barrier, GDELT ratio) that could be offloaded to parameter or output descriptions. The front-loaded main purpose is clear, but conciseness is poor.

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 missing output schema, the description comprehensively covers the response structure, segment details, diagnostics, caching, and tradeable-edge knobs. It explains why Fed bets are not ranked, making it complete for a complex tool.

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

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

Schema coverage is 100% with detailed descriptions. The description adds high-level context (e.g., 'tradeable-edge knobs') but does not substantively augment parameter meaning beyond the schema.

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

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

The description clearly states the verb 'scan' and resource 'top Polymarket markets' to return divergent opportunities. It differentiates from siblings by focusing on Pipeworx data disagreement and the 'what should I bet on today' use case.

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

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

The description implies usage for daily opportunity discovery but does not explicitly compare to sibling tools like polymarket_edge_tracker or polymarket_fill_risk. Lacks 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 read-only, idempotent, non-destructive behavior. The description adds substantial context: explains the response structure (tracked, expired, snapshot_dates), data interpretation (decay from daily closes, not intraday), and limitations (60-day TTL, snapshot gaps). This fully covers behavioral expectations beyond the annotations.

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

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

The description is front-loaded with the core purpose and question, followed by args, response details, and limits. While somewhat lengthy, each sentence contributes value. It is structured and clear, with 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 lack of an output schema, the description thoroughly documents the return fields and their meanings, plus important caveats (e.g., decay calculation, snapshot gaps). This provides the agent with sufficient context to consume the tool's output correctly.

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

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

Both parameters (days, window) are described in the schema with defaults and ranges. The description repeats this information (defaults, max for days) but does not significantly add new semantic meaning beyond what the schema already provides. With 100% schema coverage, baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose: providing edge persistence and decay telemetry from daily snapshots. It answers a specific question ('how long has this edge existed and is it shrinking?') and distinguishes its value from sibling tools like polymarket_edges by focusing on historical context. The verb and resource are well-defined.

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 the use case (analyzing edge persistence) and implicitly contrasts a new edge vs an old one, but it does not explicitly state when to use this tool versus alternatives (e.g., polymarket_edges or polymarket_arbitrage). No clear when-not-to-use guidance or alternative naming is provided, so it's minimally adequate.

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

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

The description discloses detailed behavioral traits beyond annotations: it walks the order-book ladder, computes vwap fill price, slippage, etc., and identifies thin legs and forced directional risk. It is consistent with annotations (readOnlyHint, idempotentHint) and adds context about the tool's non-destructive, read-only nature.

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

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

The description is long but well-structured with clear sections for single-market and basket modes, using bold headings and bullet-like phrasing. Front-loads the core purpose. While slightly verbose, the detail is warranted given the tool's complexity and two distinct modes.

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), the description covers return fields (top_of_book, vwap_fill_price, slippage_pp, etc.), risks (thin legs, forced directional risk), and usage context. It is comprehensive enough for an agent to understand the tool's capabilities and limitations.

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 (100% coverage), and the tool description adds significant extra context: e.g., how size_usd differs between single-market and basket modes, side auto-detection logic, and examples of slug vs URL input. This goes beyond the schema and provides practical usage guidance.

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

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

The description clearly states the tool's purpose: a realizable-vs-theoretical edge check against live order-book depth. It distinguishes between single-market and basket modes, using specific verbs like 'walk the ladder' and 'returns'. It also differentiates from sibling tools like polymarket_arbitrage and polymarket_edges by contextualizing when to use this tool.

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

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

The description explicitly states when to use the tool: before acting on polymarket_arbitrage signals or trades above ~$500. It explains the consequences of not using it (partial fills leading to unhedged positions). It also specifies prerequisites (one of market or event) and default parameter 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?

Annotations already declare readOnlyHint, idempotentHint, and no destruction. The description adds substantial behavioral context: explains two modes, response structure (leg-by-leg prices, top_spreads_pp), safety fields (compatibility_warning with two sub-cases, temporal_alignment, skipped counters). This fully informs an agent about what the tool does and when results are meaningful.

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

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

The description is front-loaded with purpose, then details modes, response, and safety fields in a logical order. While comprehensive, it is slightly verbose (e.g., repeating 'pre-mapped ≠ tradeable' twice) and could be tightened. Still, it earns its length for the complexity.

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

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

The tool is complex with no output schema, so the description must explain return values and edge cases. It covers leg-by-leg prices, top_spreads_pp, compatibility_warning (two cases), temporal_alignment, and skipped counters. An agent can understand when spreads are valid and when they are not, making it complete for effective use.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining the topic shortcut list (10 macro shortcuts), the explicit override behavior for kalshi_event_ticker and polymarket_event_slug, and example values. This functional enhancement raises the score above baseline.

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

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

The description opens with 'Cross-venue spread between Kalshi and Polymarket for the same resolving question,' explicitly stating the tool's function: computing price differences across two prediction markets. It distinguishes itself from siblings like polymarket_arbitrage (intra-venue) by focusing on cross-venue comparison, and lists unique features like two modes and safety fields.

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

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

The description gives clear context on when to use the tool: for comparing same resolving question across venues. It explains two modes and warns that pre-mapped topics often return compatibility warnings, guiding expectation. However, it doesn't explicitly state when to prefer alternatives like polymarket_arbitrage, though the cross-venue focus is implicit.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the tool is safe. The description adds context: scoping to user identifier and the dual behavior (list keys if key omitted). No contradictions.

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

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

The description is informative but slightly verbose (4 sentences). It could be more concise by omitting examples of what to store. However, it is front-loaded with the core purpose.

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

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

The description explains what the tool does and its scoping, but it does not describe the return format or type of values. Given no output schema, this lack of detail limits completeness for an agent.

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

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

Schema coverage is 100% for the 'key' parameter. The description adds meaning beyond the schema by explaining that omitting the key lists all saved keys, clarifying the dual functionality.

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 retrieves saved values or lists keys, with specific verbs ('retrieve', 'list') and resource ('saved keys'). It distinguishes from sibling tools like 'remember' and 'forget' by naming them as pairs.

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

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

The description explains when to use the tool (look up context stored earlier, avoid re-deriving) and mentions pairing with remember/forget. It does not explicitly state when not to use, but the context is clear.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds only 'most recent public uploads' and 'tag-filtered', which do not significantly extend behavioral context beyond what the annotations imply. No mention of rate limits, pagination, or data freshness.

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, front-loaded sentence of 8 words with zero waste. It efficiently communicates the core purpose and optional filtering.

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

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

For a simple read-only filtered list tool with comprehensive schema (100% param descriptions) and annotations, the description is largely sufficient. It implicitly covers default behavior (no tags = all recent uploads) but could benefit from stating the default limit or tagmode. Lacks some completeness but not critical.

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

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

Schema description coverage is 100%, with each parameter (tags, limit, tagmode) adequately described. The description adds no new parameter meaning beyond 'optionally tag-filtered', which is already implied by schema. Baseline 3 is appropriate.

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

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

The description 'Most recent public uploads, optionally tag-filtered' clearly states the verb (get), resource (public uploads), and scope (most recent, tag-filtered). It distinguishes itself from siblings like 'by_user' and 'by_group' which focus on specific 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?

The description provides no explicit guidance on when to use or not use this tool. It does not mention alternative tools or context such as 'use for exploring trending content' or 'not for user-specific feeds'.

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

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

Annotations declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds behavioral context beyond annotations, such as the effect of mark_read on flagging events as read and the return of specific fields. No contradictions observed.

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 at 4 sentences, each adding value. It is front-loaded with the main purpose, and every sentence contributes to understanding usage, behavior, or alternatives without redundancy.

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

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

Given 5 optional parameters and no output schema, the description covers return fields, filter usage, side effects of mark_read, and an alternative endpoint. It is almost complete, though it could explicitly mention limit behavior or pagination for completeness.

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

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

Schema coverage is 100% with parameter descriptions. The description adds meaning beyond the schema by explaining the purpose of filters (e.g., 'Filter by type (e.g. "sec_8k")') and the behavior of mark_read. It provides context like 'pipeworx:// when available' that enhances parameter understanding.

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

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

Description starts with 'Pull fired events from your subscription feed' indicating a clear verb+resource. It specifies returning recent alerts with fields like source and citation_uri. While it doesn't explicitly distinguish from siblings like 'list_subscriptions' or 'recent', the focus on subscription feed alerts provides sufficient clarity.

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

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

The description states 'Polls work fine; the same feed is also at GET registry.pipeworx.io/alerts.json for scripts and dashboards,' offering an alternative usage scenario. It explains when to set mark_read for subsequent calls. However, it doesn't explicitly exclude usage with other sibling tools or provide 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 show read-only, open-world, idempotent, non-destructive. Description adds rich behavioral context: fans out to multiple sources with fallback logic, soft-failure for USPTO, output structure with changes[] and citation URIs. No contradictions.

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

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

Single focused paragraph, front-loaded with purpose and examples. Could slightly compress the source list but overall efficient and clear.

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 3 required params and no output schema, description covers all relevant aspects: input formats, source behaviors, fallback logic, output structure, and alternative tool. No gaps for an agent to interpret.

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 meaningful guidance: explains 'since' accepts ISO or relative shorthand with examples, clarifies 'value' as ticker or CIK, and notes 'type' is limited to 'company'.

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

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

Description clearly states it provides a 'change feed for a company in the last N days/weeks/months' with concrete example queries. It distinguishes from sibling 'entity_profile' by specifying the static-profile alternative.

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 (recent changes over a window) and when not to ('Use entity_profile instead when you want the static profile'). Provides example queries and typical 'since' value ('30d').

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?

Disclosures beyond annotations: explains key-value pair storage scoped by identifier, persistent vs 24-hour retention. Annotations already indicate idempotent and non-destructive, but description adds invaluable 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?

Four concise sentences front-loading the core action, then usage, then storage details. No wasted words, each sentence serves a distinct 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?

Completely describes a simple key-value store tool without output schema. Explains purpose, usage, storage semantics, and lifecycles. No gaps given tool 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?

Input schema covers both parameters with clear descriptions (key name conventions, value type). Description provides usage examples but adds no additional semantic constraints or format details beyond schema, meeting baseline for high coverage.

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

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

The description clearly states the tool's purpose: 'Save data the agent will need to reuse later' with concrete examples (ticker, address, preference). It distinguishes itself from sibling tools like 'recall' and 'forget' by specifying the storage action.

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

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

Explicit usage guidance: 'Use when you discover something worth carrying forward' and directs to pair with 'recall to retrieve later, forget to delete'. Also covers persistence differences between authenticated and anonymous sessions.

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

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

Annotations already declare readOnly, idempotent, non-destructive. Description adds internal cascading behavior and detailed return format for each entity type, which is valuable beyond the annotations.

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

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

Well-structured, front-loaded with examples and purpose, then detailed type breakdown. Every sentence adds unique value; no 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?

No output schema exists, but description fully covers return values for both types, including citation URIs. Also explains internal complexity. Complete for a lookup tool with two params.

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

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

Schema covers 100% of parameters with basic descriptions. Description adds real-world examples of valid values (e.g., 'AAPL', 'ozempic') and clarifies input flexibility, enhancing understanding.

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

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

The description clearly states it resolves names to official identifiers, using natural language examples. It specifies when to use ('Use FIRST whenever you have a name but need an ID') and distinguishes from siblings like entity_profile which require an ID already.

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 ('Use FIRST...') and explains it replaces multiple manual lookups. Does not explicitly list when not to use or name alternatives, but the context is strong and the purpose is clear.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint as false. The description adds valuable context: it calls ai_visibility_check per entity, ranks by score, and returns a list with score, confidence, and signal density. No contradictions.

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

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

The description is a concise paragraph (3 sentences) that front-loads the primary purpose. Every sentence adds value without redundancy or unnecessary detail.

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

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

For a tool with 4 parameters, no output schema, but rich annotations, the description fully covers the return format, process, parameter semantics, and special handling of the first entity. It is complete enough for an agent to use correctly.

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

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

Schema coverage is 100%, but the description adds meaning beyond schema: the first entity is treated as 'subject' for narrative, models are explained with defaults and API key requirements, and context is for disambiguation. This provides extra guidance for parameter usage.

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

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

The description clearly states the tool compares AI visibility across entities side-by-side, using a specific verb 'compare' and resource 'AI visibility'. It distinguishes from siblings like ai_visibility_check (single entity) and compare_entities (generic) by specifying it probes each entity and ranks them.

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

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

The description provides a clear use case ('competitive AI-marketing audits') and an example question ('does Claude know about us as well as our competitors?'). It implies when to use (multi-entity comparison) versus single-entity check, but does not explicitly exclude other tools or state alternatives, leaving minor room for improvement.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint false. Description adds critical behavioral details: partial failures (bundlephobia first measurement can take 5-30s, sources_failed lists timeout), return structure, and ecosystem limitation.

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 front-loaded purpose statement. Every sentence adds essential information: composite check, when to use, return contents, ecosystem scope, partial failure behavior. No redundancy.

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

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

Given the complexity (multi-source, partial failures, no output schema), the description covers all necessary aspects: input, return fields, edge cases, ecosystem limitation, alternative for other ecosystems.

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. Description adds value by noting scoped packages are accepted and that version defaults to latest. This aids correct usage 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 it is a composite check for evaluating npm packages, covering safety, popularity, and size. Distinguishes from siblings by specifying it fans out across deps.dev and bundlephobia and is NPM-only.

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: for questions about safety, popularity, size, or cost of adding a package. Also notes when not to use: for non-NPM ecosystems, directing to deps.dev:version directly.

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

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

Annotations declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds valuable behavior: returning passages with character offsets and similarity scores, using BGE-base-en embeddings with cosine over 500-char windows, and a 200K char cap with truncation flagging. No contradictions.

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

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

The description is a single paragraph of about six sentences, front-loaded with the core purpose. Each sentence adds essential information: use case, output features, pairing, and technical details. No wasted words.

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

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

Despite no output schema, the description explains the return format (passages with offsets and scores) and technical constraints (200K char cap, embedding details). It fully prepares an agent to invoke the tool correctly, given the tool's moderate complexity.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning by providing example queries ('supply-chain risk', 'fiscal year 2024 revenue') and elaborating on the text parameter's truncation behavior. This goes beyond the schema's basic 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 'semantic search INSIDE a fetched record', with a specific verb ('search') and resource ('a fetched record'). It distinguishes from sibling tools like ask_pipeworx_grounded by explaining how they pair together, making the purpose unmistakable.

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

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

The description explicitly advises using the tool when a record is 'too big to cram into the prompt' and explains its benefit of saving context. It also pairs with ask_pipeworx_grounded, giving clear context. However, it does not explicitly exclude scenarios or mention alternatives among the many other 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?

Beyond annotations (readOnlyHint=false, idempotentHint=true), the description details behavioral traits: requires a persistent account, returns subscription ID, different delivery channel behaviors (feed always on, email/SMS optional, webhook HMAC-signed with auto-disable after 10 failures), and rate limit on SMS (10/day). It adds significant context not present in annotations.

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

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

The description is front-loaded with the core purpose and return value, then structured by type and delivery channel. It is fairly long but every sentence adds meaningful detail; it could be slightly trimmed but remains efficient for the complexity.

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

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

Given the tool's complexity (3 params, nested objects, no output schema), the description covers required and optional fields, their constraints, and return value. It lacks explicit mention of idempotency (though annotations cover it) and how to use the returned ID, but overall it is sufficiently complete for an agent.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value beyond schema by expanding on specific parameter examples (e.g., items:['5.02'] for sec_8k, topics for polymarket_edge) and constraints (e.g., webhook signing secret returned once, SMS must be verified). It also clarifies that the feed is always on.

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 creates a proactive monitoring subscription to live-data event streams and distinguishes it from siblings like list_subscriptions and unsubscribe. It provides specific verb+resource (subscribe to alerts) and context about what it returns (subscription ID).

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 includes prerequisites (Pipeworx OAuth account, no anonymous/BYO) and lists supported types and delivery channels. It implies when to use (to create subscriptions) but does not explicitly state alternatives for listing or removing subscriptions, though sibling tools cover those.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds context about the output format (category-bucketed example questions with tool+argument shape) and the fact that it draws from a live catalog of thousands of tools, which is beyond what annotations provide.

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

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

The description is somewhat lengthy but well-structured, starting with the purpose, listing example queries, then describing output and usage. Every sentence adds value, though some slight redundancy could be trimmed without losing clarity.

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

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

Given no output schema, the description fully explains the return value (category-bucketed example questions). Annotations cover safety and idempotency. The description also covers when to use the tool (first interaction) and how to use meta-tools, making it complete for the tool's purpose.

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

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

Schema coverage is 100% with one optional parameter 'topic'. The description adds concrete examples of topic values (finance, pharma, etc.) and explains the effect of omitting vs providing topic, adding significant meaning beyond the schema's brief 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 is an onboarding entry point that returns category-bucketed example questions. It distinguishes itself from siblings like ask_pipeworx (which actually answers questions) and discover_tools (which lists tools) by specifying its role as a 'first use' tool.

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

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

Explicitly says 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools (ask_pipeworx, entity_profile, compare_entities, etc.).' It also explains when to omit vs pass a topic argument, providing clear guidance.

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

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

Annotations indicate readOnlyHint=false, destructiveHint=false, and idempotentHint=true. The description adds value by explaining that the subscription is deactivated (not deleted) and that ownership is enforced, which is beyond the annotations. No contradiction.

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

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

The description is two sentences, front-loaded with the main action, and every sentence adds necessary detail without redundancy. It is concise and well-structured.

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

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

Given the tool's simplicity (one required parameter, no output schema, and clear annotations), the description is complete. It covers the action, ownership, and the soft-deactivation behavior, leaving no ambiguity for an AI agent.

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

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

The single parameter 'id' has a description in the schema stating 'Subscription id (uuid) returned by subscribe.' With 100% schema coverage, the description does not add new semantics but confirms the parameter's origin, which is helpful but not essential.

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', specifying the verb 'cancel' and resource 'subscription'. It further distinguishes by noting ownership enforcement and that the row is deactivated, not deleted, setting it apart from siblings like 'subscribe' or 'list_subscriptions'.

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

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

The description provides clear context for usage: ownership is enforced, so only own subscriptions can be canceled. It also explains the deactivation behavior. However, it does not explicitly state when not to use this tool or suggest alternatives, but given the simplicity, the context is sufficient.

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

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

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint. The description adds context about the data source (SEC EDGAR + XBRL), return types (verdict with delta and citation), and performance benefit (replaces multiple calls). No contradictions.

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

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

The description is a single paragraph but front-loaded with user query examples. It efficiently covers purpose, usage, scope, and return value. While dense, each sentence adds value; could be slightly more structured but remains concise.

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

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

Given one parameter and no output schema, the description adequately explains what the tool returns (verdict, actual value, citation, delta) and its data source. It covers the main use case and limitations (v1 supports company-financial). Missing error handling details but acceptable for a read-only tool.

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

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

Schema coverage is 100% with a clear description of the 'claim' parameter and an example. The description reinforces this with examples of natural-language claims, adding clarity but not new semantic information 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 identifies the tool as a natural-language claim verifier for company-financial claims, using specific verbs like 'fact check', 'verify', and 'confirm or refute'. It distinguishes itself from siblings by specifying the domain and stating it replaces multiple sequential calls.

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

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

The description explicitly advises 'Use whenever the agent needs to check whether something a user said is factually correct.' It also limits scope to company-financial claims, implicitly guiding when not to use. However, it does not explicitly mention alternative tools for non-financial claims.

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