Doaj

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

Annotations already declare readOnly=true, etc. Description adds value by detailing output format (per-model + combined), that the API key is passed directly, and the scoring range. No contradictions with annotations.

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

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

Two efficient sentences: first explains core function and default; second adds optional behavior and return shape. No wasted words, front-loaded with key info.

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 covers expected return structure (score, confidence, signals, raw_response) and usage scenarios. All 4 parameters addressed with sufficient detail. Complex enough for agent to invoke correctly.

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

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

All 4 parameters are described in schema (100% coverage). Description adds context: default model value, optional Anthropic key purpose, and that 'context' disambiguates. Examples given for entity. Exceeds 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?

Description clearly states the verb (Probe) and resource (LLMs for visibility scoring), with specific outputs (score 0-100). Distinguishes from siblings by focusing on AI visibility audits, not general Q&A or entity resolution.

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

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

Provides clear context: default model, optional Anthropic key, when to omit models. No explicit when-not-to-use, but the purpose is narrow enough to stand alone. Siblings like 'ask_pipeworx' or 'scan_competitor_ai_presence' serve different goals.

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

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

Annotations already provide readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. Description adds that it returns structured answers with citation URIs and automatically fills arguments, which is valuable 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 somewhat long but well-structured with clear sections (preference, examples, step-up guidance). Every sentence adds value, though some redundancy could be trimmed.

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

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

Given the tool's complexity (4,552 tools, 1,160 sources), the description is comprehensive: explains functionality, use cases, alternatives, and provides examples. No output schema but description sufficiently covers return value.

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

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

Schema coverage is 100%, but description explains that the question parameter accepts multiple aliases (q, text, input, query, prompt) and provides example queries, adding 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 uses specific verbs ('routes', 'fills arguments', 'returns structured answer') and clearly distinguishes from siblings like ask_pipeworx_grounded and deep_research by outlining when to use each.

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 preference over web search, provides example queries, and gives step-up guidance for alternatives with specific use cases (hallucination-resistant answers, broad multi-part questions).

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

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

Discloses behavioral traits beyond annotations: costs one extra LLM call, returns structured refusal reasons (not_in_source, no_tool_match, etc.), and details return format. No contradiction with annotations.

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

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

Well-structured with key point upfront. Every sentence adds value, though slightly verbose; could be tightened slightly 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 return values (success and refusal), behavior, and use cases. Completes the tool definition comprehensively.

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

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

Schema coverage is 100%, so baseline is 3. Description lists aliases but adds no semantic meaning beyond what the schema provides. No additional parameter details.

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

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

The description states it is a 'hallucination-resistant answer mode for high-stakes reads' that extracts answers using only tool result, clearly distinguishing from sibling 'ask_pipeworx' which does not guarantee factuality.

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: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts' with examples like financial verdicts, legal claims. Also explicitly says 'prefer ask_pipeworx for casual lookups', providing a clear alternative.

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 goes far beyond annotations, detailing the resolution process, market match confidence levels, parent event extraction, news fallback mechanisms, safety short-circuits, wide-spread warnings, and cancellation rules. All behavioral traits are transparently disclosed without contradiction to annotations.

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

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

The description is very long and dense, though well-structured with sections (CLASSIFIERS, FAN-OUT EXAMPLES, etc.). It could be more concise; the first sentence states purpose, but the length may hinder quick comprehension.

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

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

Given the tool's complexity and lack of output schema, the description thoroughly explains return values (result.market, result.analysis, result.evidence), resolver contract, parent event, news fields, and edge cases. It provides a complete picture for an AI agent to understand and invoke the tool correctly.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining parameter usage (e.g., 'market' can be slug, URL, or question text; 'depth' enum values; 'include_raw' guidance). This exceeds the baseline by providing contextual meaning beyond the schema.

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

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

The description clearly states the tool's purpose: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies input types (slug, URL, question text) and output (evidence packet + market-vs-model comparison). Usage examples and explicit 'Use for' statements distinguish it from sibling tools like polymarket_edges.

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

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

The description provides explicit usage scenarios ('should I bet on X', 'what does the data say about Y') and includes examples. It does not explicitly state when not to use, but it covers fallback and safety behaviors. No direct comparison to alternatives, but the context is clear.

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

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

The description adds significant behavioral context beyond annotations: it specifies data sources (SEC EDGAR/XBRL for companies, FAERS for drugs), handles off-calendar fiscal years correctly, sorts results by primary metric, and returns paired data with citation URIs. Annotations already indicate read-only, open-world, idempotent, non-destructive behavior, and the description aligns with and enriches those traits.

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, with bolded natural language triggers and a clear breakdown of behavior per type. Every sentence adds value, though some repetition of patterns could be trimmed slightly.

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

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

The description covers all necessary aspects for a comparison tool: entity types, data sources, behavior across fiscal years, sorting, and output format (paired data + citation URIs). No output schema is provided, but the description adequately explains what the tool returns, making it complete for an AI agent to understand and invoke correctly.

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

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

With 100% schema coverage, the description adds meaning beyond the schema by explaining the data context for each type (e.g., 'pulls LATEST 10-K revenue + net income + cash + long-term debt' for company, 'FAERS adverse-event counts, FDA approval counts' for drug). It also provides examples and constraints (2–5 items, tickers vs drug names).

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: side-by-side comparison of 2–5 companies or drugs in a single parallel call. It provides natural language triggers ('Compare X and Y', 'X vs Y') and distinguishes itself from the sibling tool 'entity_profile' by replacing sequential lookups, making it clear and differentiated.

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

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

The description includes an explicit instruction to prefer this tool over sequential single-pack lookups when comparing entities. It explains the data returned for each type (company: financials, drug: adverse events, etc.) but does not provide explicit exclusion criteria or alternative tools for non-comparison tasks.

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 rich behavioral context beyond annotations: requires account, expects 15-60s response time, decomposes into facets, routes to 4,552 tools in parallel, returns evidence with citations and explicit gaps[], and never invents. This complements the readOnlyHint, openWorldHint, and idempotentHint annotations without contradiction.

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

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

The description is front-loaded with critical info (account requirement, alternative) and well-organized, but it is relatively long. Every sentence serves a purpose, but minor trimming could improve conciseness without losing value.

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

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

The description fully explains what the tool returns (findings packet with verbatim evidence, confidence, source, fetched_at, citation, gaps[]), mentions expected duration, and clarifies limitations (empty gaps for non-structured topics). No output schema exists, so this level of detail is essential and provided.

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?

Despite 100% schema coverage, the description adds significant meaning: explains depth enum values map to 3/5/8 facets, specifies that 'standard' is default, and clarifies that the question parameter accepts broad/multi-part questions. This goes beyond the schema descriptions.

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

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

The description clearly states the tool's purpose: 'Grounded multi-source research across Pipeworx's 1160 STRUCTURED data sources' with decomposition and parallel routing. It distinguishes from siblings by explaining it is not open-web search and explicitly contrasts with ask_pipeworx for single lookups and breaking news.

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

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

The description provides explicit guidance: when to use (broad/multi-part questions over structured data), when not to use (single lookup -> ask_pipeworx; breaking news -> ask_pipeworx), and prerequisites (account required, with tier limitation for 'thorough' depth). An alternative (ask_pipeworx) is named for unsigned users.

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

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

Annotations already declare read-only and idempotent. The description adds that each result is 'ready to call directly, no second schema lookup needed,' which is valuable operational detail. Could mention that it never modifies state, but annotations cover the core safety profile.

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

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

Two sentences: first states purpose, second gives detailed examples, return value, and usage advice. No filler; every sentence earns its place. Front-loaded with the core action.

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

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

Despite no output schema, the description thoroughly explains what is returned (top-N tools with complete info) and when to call. With 36 sibling tools and no output schema, this description is fully sufficient for an agent to use the tool correctly.

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

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

Schema coverage is 100%, so baseline is 3. The description adds context by explaining the query parameter accepts natural language and lists multiple aliases. This goes beyond the schema's description, justifying a 4.

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 ('Find tools') and the resource ('tools'), and specifies that it returns top-N relevant tools with full schemas. It distinguishes from siblings by being a meta-discovery tool, not a domain-specific query 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 advises to call this FIRST when many tools are available and you need to see the option set. Also enumerates use cases: browse, search, look up, discover. Provides clear when-to-use guidance.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false. Description adds details about patent soft-failure (USPTO sunset May 2025), fan-out behavior, and return structure. 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 dense paragraph with examples upfront, then details. Well-organized chronologically, but slightly long. Could be more concise without losing content.

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

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

No output schema, but description enumerates return fields (cik, filings, fundamentals, patents, news, LEI) with specifics (e.g., 5 filings, pipeworx URIs). Mentions patent soft-failure. Lacks error handling details, but acceptable for a profile tool.

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

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

Schema covers both parameters with descriptions (coverage 100%). Description reinforces key constraints: type limited to 'company' for now, value must be ticker or zero-padded CIK, names unsupported. Adds emphasis but largely echoes schema.

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

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

The description clearly states the tool's purpose: providing a full cross-source profile of a US public company. It uses specific verbs ('profile', 'research', 'brief') and lists data sources (SEC, XBRL, USPTO, news, GLEIF), distinguishing it from siblings 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?

Explicitly advises preferring this tool over chaining multiple lookups for a holistic view. Specifies accepted inputs (ticker or CIK) and directs users to resolve_entity for names. Provides clear when-to-use and when-not-to-use guidance.

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

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

Annotations already indicate destructive and idempotent behavior. Description adds context about clearing sensitive data but does not significantly extend beyond what annotations convey.

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

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

Two concise sentences with front-loaded action and clear usage guidance; no extraneous text.

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, strong annotations), the description fully covers purpose, usage, and behavioral context.

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

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

Schema coverage is 100% and description of the single parameter ('key') is already in the schema. Description adds no additional parameter semantics.

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

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

Description clearly states the action ('Delete a previously stored memory by key') and explicitly names sibling tools ('Pair with remember and recall'), distinguishing its purpose.

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

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

Provides explicit when-to-use conditions ('context is stale, task is done, clear sensitive data') and mentions alternative tools, giving 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 already provide safety profile (read-only, idempotent). Description adds process details (fetches, extracts, emits markdown) and output format, enhancing transparency. No mention of limitations or error cases, but still strong.

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, no filler, front-loaded with purpose. Every sentence adds value, and the structure is optimal.

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 two-parameter tool with no output schema, description adequately explains output format and behavior. Lacks error handling or edge case info, but given the tool's simplicity, it is reasonably complete.

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

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

Schema coverage is 100%, so schema already documents both parameters fully. Description repeats the defaults (max_links default 25, max 50) but does not add significant new meaning beyond schema.

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

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

Description clearly states it generates a production-ready llms.txt file for any URL, with specific use cases. Distinguishes itself from sibling tools by focusing on a unique, specific output.

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

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

Explicitly lists three use cases (client indexing, own project, competitor auditing). Does not mention when not to use or alternatives, but given the uniqueness of the tool, this 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 provide readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds no behavioral context beyond what annotations supply, contributing minimal value.

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 that is direct and to the point, with no unnecessary words.

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

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

For a simple fetch tool with one required parameter and an output schema, the description is sufficient. It could optionally hint at the return value, but the presence of an output schema compensates.

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

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

Schema coverage is 100% and the description only repeats the schema's mention of 'DOAJ id'. No additional meaning or details are added 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 action ('Fetch'), the resource ('an article'), and the identifier ('by DOAJ id'). It distinguishes from sibling tools like 'get_journal' and 'search_articles'.

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

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

No explicit guidance on when to use this tool versus alternatives. It is implied that one would use it when they have a specific DOAJ id, but no when-not or alternative suggestions are provided.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety and idempotency profile. The description adds no behavioral context beyond what annotations already provide, so it meets the baseline without adding extra value.

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 that is perfectly front-loaded: the purpose is immediately clear. Every word is necessary and earns its place.

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

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

Given a simple fetch operation with an output schema and comprehensive annotations, the description is adequate. However, it lacks any usage context or guidance on error handling or return format, which could be helpful. Still, it is largely complete for its intended simplicity.

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

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

Schema description coverage is 100% (the 'id' parameter is described in the schema). The description merely restates 'by DOAJ id', which duplicates the schema's parameter description. No additional semantic context is added beyond what the schema already offers.

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

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

The description uses the specific verb 'fetch' and identifies the resource as 'journal by DOAJ id'. It clearly distinguishes from sibling tools like 'get_article' (which fetches an article) and 'search_journals' (which searches for journals without a known 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 implies usage when you have a DOAJ id, but it does not explicitly state when to choose this tool over alternatives like 'search_journals' or 'get_article'. No exclusions or alternative references are provided.

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

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

Annotations provide readOnlyHint, idempotentHint, destructiveHint, openWorldHint. Description adds details about returned fields and default exclusion of inactive subscriptions, which is beyond annotations.

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

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

Two sentences, no waste. Purpose is stated first, then return fields, then usage. Efficiently informative.

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

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

Despite no output schema, description lists return fields so agent knows what to expect. Annotations cover safety and idempotency. Simple tool with one parameter is fully addressed.

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 fully described. The description mentions 'active subscriptions' which aligns with default false for include_inactive, but adds no new meaning beyond schema.

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

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

Clear verb 'List' and resource 'subscriptions'. Describes what is returned (id, type, params, etc.). Distinguishes from sibling tools like subscribe and unsubscribe.

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

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

Explicit guidance: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' Provides context for when to use, though does not explicitly state when not to use.

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

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

Discloses rate limit (5 per identifier per day), free usage, no count against tool-call quota, and that feedback is reviewed daily affecting roadmap. This exceeds 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 comprehensive yet concise, with each sentence adding value. Front-loaded with purpose and quickly moves to usage and constraints. No redundant 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 three parameters including a nested object, the description covers purpose, usage, parameter details, rate limits, and behavioral expectations. No output schema needed; complete for agent invocation.

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

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

With 100% schema coverage, the description adds detailed meaning: clarifies enum values for 'type', explains 'context' as optional structured context, and gives specific instructions for 'message' (be specific, 1-2 sentences, 2000 chars).

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

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

The description clearly states the tool is for sending feedback (broken, missing, needs to exist) with specific categories (bug, feature, etc.), distinguishing it from sibling tools like ask_pipeworx or deep_research which are for queries and 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?

Explicit when-to-use conditions (bug, feature, etc.) and what to avoid (don't paste end-user prompt). Also provides rate limit and quota information, guiding agent on proper invocation.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds valuable behavioral context beyond these: data source (CF analytics-engine), privacy (no PII), caching behavior (5min-1h depending on window), and aggregate nature. This fully equips the agent with behavioral expectations.

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: two sentences for core functionality, then bullet-listed use cases, then data source and caching details. No filler. Every sentence adds value, and key information is front-loaded.

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

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

Given the single optional parameter, rich annotations, and no output schema, the description fully covers what the tool does, how to use it, when to use it, its data provenance, privacy characteristics, and performance (caching). No gaps remain for the agent to infer.

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

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

Input schema has 100% coverage with description for the single 'window' parameter. The description adds contextual meaning by explaining how window choices affect results ('shorter windows surface what's hot right now; longer windows show steady-state demand'). This enriches the schema beyond enum values.

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

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

The description clearly states it returns 'top tools, top packs, and total call volume' over configurable time windows. It distinguishes itself from siblings like 'discover_tools' by focusing on trending data derived from actual AI agent usage, not static tool lists.

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

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

The description provides three explicit use cases: discovering hot data sources, confirming canonical tool choice, and aligning use case with agent needs. It does not explicitly state when not to use, but the positive guidance is clear and sufficient for an agent to decide.

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

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

Provides extensive behavioral details beyond annotations: trending scan scope, partition check, semantic anchor, placeholders filter, fill check against live CLOB depth, and response structure. No contradictions with annotations.

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

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

The description is front-loaded with the purpose, then structured into clear sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK). Every sentence adds value, and it is appropriately detailed for a complex tool.

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

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

Completeness is high: describes output structure (opportunities array, partition check data), explains fill check, and covers all modes. Despite no output schema, the description compensates adequately.

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

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

The input schema already has descriptions for both parameters (100% coverage). The description adds significant extra context: event parameter accepts slugs or full URLs, topic parameter explains cross-event scanning, and default behavior for no args is also covered.

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 finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It specifies verb, resource, and distinguishes two modes (event and topic) plus a default trending scan.

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

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

Explicit guidance on when to use each mode: no args for trending scan, event for per-event partition check, topic for cross-event scanning. It also mentions using polymarket_fill_risk for custom sizing, providing an alternative.

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 extensive behavioral context beyond the annotations: caching (1h KV), diagnostics for empty segments, Fed bets exclusion with reasoning, and per-opportunity fields. All annotations (read-only, idempotent, non-destructive) are consistent with the description.

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

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

The description is dense and lacks clear structure (paragraph format). While all information is present, it could benefit from bullet points or clearer sectioning to improve readability. It is not concise but is packed with 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?

Despite no output schema, the description fully covers response structure (by_segment with three segments, fields per opportunity, diagnostics, Fed bets note, caching). Given the tool's complexity (9 parameters, three models), this is complete and allows an agent to understand what to expect.

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

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

Schema coverage is 100%, so parameters already have good descriptions. The tool description adds value by explaining parameter groups (tradeable-edge knobs) and how they interact, e.g., min_partition_leg_kelly's purpose for partition edges. This contextual information enhances understanding beyond individual schema descriptions.

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

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

The description clearly states the tool scans Polymarket markets for opportunities where Pipeworx data disagrees with market price, with a specific verb and resource. It distinguishes from siblings by focusing on Pipeworx model-driven edges, as opposed to cross-platform arbitrage tools like polymarket_arbitrage.

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

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

The description positions the tool for 'what should I bet on today', implying when to use it for discovering betting opportunities. It does not explicitly compare to alternatives or state when not to use it, but the detailed model families and knobs provide clear context for appropriate usage.

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

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

The description adds significant behavioral context beyond annotations: it explains that snapshots are daily, gaps indicate no scan, decay is based on daily closes (not intraday), and history is bounded by a 60-day TTL. No contradictions with annotations (readOnlyHint, idempotentHint, etc.).

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

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

The description is well-structured with clear sections: purpose, Args, RESPONSE, LIMITS. It is front-loaded with the core question. However, some parts are verbose (e.g., detailed breakdown of trend values). Still, it earns its length given 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?

With no output schema, the description fully explains the response format (tracked[], expired[], snapshot_dates[]) including field meanings. It covers all aspects: parameters, data sources, limitations, and computation of trend/decay. Complete for the tool's complexity.

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

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

Schema coverage is 100%, but the description adds meaning by providing defaults (days: 14, window: '1wk') and constraints (max 30 for days, clamp 2-30). This goes beyond the schema descriptions and helps the agent select proper values.

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

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

The description clearly states that the tool provides edge persistence and decay telemetry from daily snapshots, answering how long an edge has existed and if it's shrinking. It distinguishes itself from the sibling tool 'polymarket_edges' by focusing on historical tracking rather than current edges.

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

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

The description implicitly guides usage by contrasting fresh vs. old edges and explaining that a 3-week-old wide edge is different from a fresh one. It also mentions limits like the 60-day TTL. However, it does not explicitly name alternatives or provide explicit when-to-use/when-not-to-use guidelines.

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, returns specific fields like top_of_book, slippage, verdict, etc. It explains automatic side detection in basket mode and highlights forced directional risk. Annotations (readOnlyHint, idempotentHint) are consistent with the description, and no contradictions exist.

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

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

The description is front-loaded with the core purpose and structured with clear mode separation. While it is dense, every sentence adds value. Slightly verbose, but still well-structured 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?

Despite lacking an output schema, the description lists all return fields for both modes (e.g., top_of_book, vwap_fill_price, capture_ratio, thin_legs, forced_directional_risk). It covers edge cases like partial fills and thin books, making the tool self-contained and complete 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?

Schema description coverage is 100%, but the description adds significant meaning: it explains the different interpretations of size_usd for single-market vs. basket, the auto-detection of side in basket mode, and default values. This goes well beyond the schema's parameter descriptions.

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

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

The description clearly identifies the tool's purpose as a realizable-vs-theoretical edge check against live order-book depth. It distinguishes between single-market and basket modes with specific verbs and resources. The explicit statement 'USE THIS before acting on any polymarket_arbitrage...' differentiates it from sibling tools.

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

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

Provides explicit when-to-use guidance: before arbitrage signals or trades above $500. Also explains when not to use, such as when theoretical overround is not capturable on thin books, and warns against partial basket fills leading to unhedged positions.

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

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

Beyond the readOnlyHint annotation, the description details safety fields (compatibility_warning, temporal_alignment, skipped_cross_type) and explains exactly what each means for cross-venue comparability. It tells agents when spreads are mathematically meaningless (e.g., temporal gaps or bet shape mismatches), going far beyond what annotations cover.

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

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

The description is well-structured with labeled sections (TWO MODES, RESPONSE, SAFETY FIELDS) and front-loaded core purpose. However, it is somewhat verbose with repeated reminders (e.g., 'pre-mapped ≠ tradeable' appears at end). Still, every sentence adds value.

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

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

Despite no output schema, the description fully specifies the response structure (leg prices, spread, safety fields) and explains each safety field's meaning. For a tool with 3 optional parameters, it provides sufficient context for correct invocation and interpretation.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds value by explaining the semantics of the two modes (topic vs explicit) and how parameters interact (e.g., 'Overrides the topic-mapped X side'). This extra context justifies a 4.

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 calculates the cross-venue spread between Kalshi and Polymarket for the same resolving question, which is a specific verb+resource combination. It distinguishes itself from siblings like polymarket_arbitrage by focusing on cross-venue spreads rather than single-venue 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?

Explicitly describes two usage modes (topic shortcuts and explicit tickers), explains when to use each, and provides clear warnings about pre-mapped topics often yielding non-tradeable spreads. The note 'pre-mapped ≠ tradeable' sets realistic expectations for when the tool is useful.

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

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

The description adds value beyond annotations by explaining the key omission behavior and scoping to identifier. It fully aligns with readOnlyHint and idempotentHint annotations, with no contradictions.

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

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

Two sentences front-load the core action and purpose, with no wasted words. Every sentence serves a distinct function: what, when, scope, pairing.

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 retrieval tool with one optional parameter and no output schema, the description covers all necessary aspects: operation, usage context, scoping, and related tools.

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

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

Schema already fully describes the key parameter (omit to list all keys). The description reinforces this but adds no new semantic information beyond schema coverage.

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

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

The description clearly states the tool retrieves a value saved via remember, or lists all keys if omitted. It distinguishes from siblings remember and forget by specifying the paired operations.

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

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

Provides explicit use cases (look up previously stored context) and scoping details. Mentions pairing with remember and forget, but lacks explicit when-not-to-use guidance, though implied by 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 declare the tool read-only, idempotent, and non-destructive. The description adds value by detailing returned fields (source, citation_uri, raw event payload) and the stateful behavior of mark_read. 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 a single compact paragraph of 4-5 sentences, front-loaded with the main purpose. Every sentence provides necessary information without fluff or repetition.

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

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

Given 5 optional parameters and no output schema, the description covers retrieval, filtering by type/date, stateful marking of read events, and an alternative ingestion method. It is sufficiently complete for an agent to correctly invoke the tool, though it omits edge cases like error handling or rate limits.

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

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

Schema coverage is 100%, so each parameter has a baseline description. The tool description adds semantic value by explaining the practical effect of mark_read ('flag returned events read so the next call only shows newer ones'), which goes beyond the schema's short description. For other parameters, the description reinforces their purpose without redundancy.

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

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

The description clearly states 'Pull fired events from your subscription feed' with a specific verb and resource. It distinguishes from sibling tools like 'list_subscriptions' and provides context that the same feed is accessible via a REST endpoint for alternative uses.

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 polling works fine and notes the direct HTTP URL for scripts/dashboards, implying when to use this tool vs. the alternative. It also explains the effect of mark_read on subsequent calls, offering practical usage guidance without exhaustive when-not conditions.

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

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

Annotations already provide readOnlyHint, etc. Description adds rich behavioral context: fan-out to SEC, GDELT/GNews, USPTO, error handling, return structure. No contradiction.

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

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

Description is packed with info and front-loaded with examples. Slightly long but every sentence adds value. Could be slightly more concise.

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

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

Covers data sources, parameter format, fallback, return structure, and distinguishes from sibling. No output schema but description gives sufficient sense of output. Complete for 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?

Schema coverage is 100%, but description adds examples for `since` (ISO, relative), recommends '30d' or '1m', and clarifies `type` is only 'company'. Adds meaning beyond schema.

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

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

The description clearly states it provides a change feed for a company over a time window, with example queries. It distinguishes from sibling entity_profile, which returns static profile.

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 this tool versus entity_profile. Also describes fan-out logic and fallbacks (GDELT→GNews, USPTO soft-fail).

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 idempotentHint=true and destructiveHint=false. The description adds scope (key-value by identifier), authentication persistence, and 24-hour retention for anonymous sessions, which are not 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?

Very concise: four sentences that each add essential information without redundancy. Front-loaded with 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?

For a simple key-value store with good schema and annotations, the description fully covers usage, behavior, and integration with sibling tools. No output schema needed.

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

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

Schema coverage is 100%, but description adds naming examples for keys (e.g., 'target_ticker') and states values can be any text, providing context beyond the schema's field descriptions.

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

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

The description clearly states the tool saves data for reuse across conversations/sessions, with specific examples (resolved ticker, target address, etc.). It distinguishes from sibling tools like recall and forget.

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

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

Explicitly states when to use: 'Use when you discover something worth carrying forward.' Also provides pairing guidance with recall and forget.

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, covering safety and idempotency. The description adds that each call cascades through several lookup endpoints internally, which is useful context about the tool's behavior. No contradictions with annotations.

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

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

The description is well-structured with examples and bullet points for each type. It is somewhat verbose but every sentence adds value. The information is front-loaded with examples and usage guidance. Minor redundancy could be trimmed, but overall efficient.

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

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

Given the tool's complexity with two entity types and multiple acceptable inputs, the description is thorough. It explains the purpose, when to use, supported inputs, return details for each type, and internal cascading. Without an output schema, the description adequately covers what is returned. Error handling or ambiguity resolution is not described, but for a lookup tool this is sufficient.

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

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

Schema coverage is 100% with two parameters described. The description adds significant meaning beyond the schema: for 'company', it specifies return fields (ticker, 10-digit CIK, company_name, citation URI); for 'drug', it specifies RxCUI, ingredient, brand, and citation. It also clarifies that 'value' for company accepts ticker, CIK, or name with auto-disambiguation.

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

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

The description clearly states the tool resolves a name to an identifier, gives example queries, and explicitly lists supported entity types. It distinguishes from siblings by positioning itself as the first step when an ID is needed, as seen in 'Use FIRST whenever you have a name but need an 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 explicitly says when to use the tool ('Use FIRST whenever you have a name but need an ID') and provides query examples. It doesn't explicitly state when not to use it, but the context implies it's not for when IDs are already known. The mention of replacing 2-3 manual lookups adds 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?

Adds behavioral details beyond annotations: probes each entity with ai_visibility_check, ranks by score, returns ranked list with score, confidence, signal density. No contradiction with readOnlyHint etc.

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

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

Three sentences, front-loaded with main verb and resource. Every sentence adds value with no redundancy.

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

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

Covers purpose, usage, outputs, and parameter nuances. Could mention minimum entity count or error states, but sufficient given complexity.

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

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

Schema coverage is 100%, but description adds value by noting first entity is treated as subject for narrative. Explains context and models parameters beyond schema descriptions.

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

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

The description clearly states the tool compares AI visibility across multiple entities side-by-side, using specific verbs and resources. It distinguishes from siblings like ai_visibility_check (single entity) and compare_entities (generic comparison).

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

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

Provides clear context for competitive AI-marketing audits with an example question. Does not explicitly state when not to use or list alternatives, but the context makes usage clear.

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

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

Beyond annotations (readOnly, idempotent), description adds behavioral details: fans out to two services, returns specific fields, per-advisory detail, links, and alternative versions. Warns about bundlephobia first measurement taking 5-30 seconds and that sources_failed will list timeouts.

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

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

Description is a few sentences but packs purpose, usage, constraints, and behavioral notes efficiently. Every sentence adds value; could be slightly trimmed but not wasteful.

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?

Even without output schema, description fully explains return data: summary block fields (is_latest, license, etc.), per-advisory detail, links, and alternative versions. Covers partial failures and NPM ecosystem limitation. Complete for the tool's complexity.

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

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

Schema coverage is 100% with clear descriptions. Description confirms package as npm name and version defaults to latest, but adds no new constraints or format hints beyond what schema already provides.

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

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

The description starts with 'Composite...check in ONE call' and specifies it fans out across deps.dev and bundlephobia. It clearly states the tool checks npm package safety, popularity, and size, distinguishing it from siblings like scan_competitor_ai_presence or entity_profile.

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

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

Explicitly says 'Use whenever an agent asks...' and provides example queries. Also specifies when NOT to use: 'NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly.' Gives alternative tool and notes graceful degradation.

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 and idempotentHint=true, so the description does not need to repeat safety traits. It adds value by explaining the Lucene-style query syntax and supported fields.

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

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

Two sentences, no filler. Purpose is front-loaded, key feature (Lucene queries) follows immediately. Every sentence is essential.

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

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

Given the presence of an output schema and 100% parameter coverage, the description is adequate. It could mention pagination limits or result ordering, but the schema covers page_size and sort.

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?

100% schema coverage means descriptions for all parameters exist. The description adds meaningful context by explaining how to use the query parameter (Lucene-style fields) beyond the schema's 'Free-text or Lucene-style query'.

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 ('Search') and the specific resource ('peer-reviewed open-access articles'), and differentiates from sibling tools like search_journals and get_article through the focus on articles and Lucene-style queries.

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

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

No explicit guidance on when to use this tool vs alternatives (e.g., search_journals, deep_research). The description does not mention when-not to use or provide exclusions.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false, covering safety and idempotency. However, the description adds no behavioral context beyond the annotations, such as pagination or result limits.

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

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

The description is extremely concise (5 words) and front-loaded. Every word is necessary, and no information is wasted.

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

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

Given the tool has 4 parameters (including optional pagination) and an output schema, the description is insufficient. It omits key aspects like pagination, query syntax (Lucene), and result behavior, leaving agents to infer from the schema alone.

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

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

The input schema has 100% coverage with descriptions for all 4 parameters. The description adds no further meaning, so the baseline of 3 applies.

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

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

The description 'Search open-access journals.' clearly specifies the action (search) and the resource (open-access journals). It is specific but does not differentiate from sibling tools like 'search_articles' or 'get_journal', which also deal with academic content.

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

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

No guidance is provided on when to use this tool versus alternatives. The description lacks context about prerequisites, filtering options, or comparison to other search 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?

The description reveals technical details beyond annotations: embedding model (BGE-base-en), chunking strategy (500-char overlapping windows), similarity metric (cosine), and character cap (200K chars with truncation flag). Annotations already declare readOnly, idempotent, etc., and the description adds substantive behavioral context without contradiction.

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

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

The description is somewhat lengthy (5 sentences) but each sentence contributes unique information. The purpose is front-loaded. Minor length could be trimmed, but it remains clear 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?

Despite lacking an output schema, the description fully explains the return format (top-N passages with offsets and scores), the algorithmic details, and the input constraints. Annotations provide safety/hints. All necessary context for correct usage is present.

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

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

The schema already describes all parameters (100% coverage). The description adds value by providing examples for the query (e.g., 'supply-chain risk') and reiterating the text max length, but these are enhancements rather than essential new information.

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

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

The description clearly states the tool performs semantic search inside a fetched record. It specifies the use case (large texts like SEC 10-K) and distinguishes from the sibling ask_pipeworx_grounded, explaining the pairing workflow.

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

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

The description explicitly says when to use this tool: 'Use when the record is too big to cram into the prompt.' It also explains how it pairs with ask_pipeworx_grounded for a two-step process, providing clear guidance on when to choose this over 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?

Adds context beyond annotations: requires OAuth, delivery channel details (feed always on, email, sms with cap, webhook with HMAC signing), and return value. 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?

Front-loaded with core purpose, then elaborates. Each sentence adds value, though slightly lengthy. 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?

Covers all parameters, types, examples, delivery details, and return value. No missing guidance for agent to invoke correctly.

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

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

Schema coverage is 100%; description adds per-type examples and delivery constraints (e.g., SMS cap, webhook secret) that go beyond schema descriptions.

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

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

Clearly states it creates a proactive monitoring subscription to a live-data event stream and returns the new subscription id. Distinguishes from siblings like list_subscriptions and unsubscribe.

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

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

Explicitly specifies when to use (proactive monitoring, requires Pipeworx OAuth account) and when not (anonymous/BYO cannot persist). Provides supported types and examples.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and not destructive. The description adds behavioral context: returns examples drawn from live catalog, can be called with or without topic. 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?

Description is comprehensive but slightly long; however, every sentence adds value. Front-loaded with common user phrases and clear purpose. Could trim some examples but overall 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 no output schema and one optional parameter, the description fully explains return type (example questions with tool+argument shape) and usage context. It also advises when to invoke, satisfying completeness for an onboarding 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 covers 100% of parameters, and description enriches by listing specific topic values (finance, pharma, etc.) and explaining the effect of omission (full spread vs. focus). Provides practical guidance beyond schema.

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

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

The description clearly states the tool returns 'category-bucketed example questions' with tool+argument shapes, serving as the onboarding entry point. It distinguishes itself from siblings by advising to use it first when unsure what Pipeworx can do, and references meta-tools like ask_pipeworx and entity_profile.

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

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

Explicitly states when to use: 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools'. Also implies not needed when user already knows specific questions.

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

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

The description discloses that the row is deactivated (not deleted) and ownership checks are performed, adding valuable behavioral context beyond the annotations (readOnlyHint=false, idempotentHint=true, destructiveHint=false). 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 extremely concise (2 sentences) with no wasted words, front-loading the primary purpose and then adding constraints.

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 (single parameter, no output schema, clear annotations), the description fully covers purpose, behavior, and constraints.

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

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

The schema coverage is 100%, and the description reinforces the parameter meaning ('by id') but does not add 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 states the action ('Cancel a subscription by id') and resource, distinguishing it from sibling tools like 'subscribe' and 'list_subscriptions'.

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

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

The description specifies that ownership is enforced and only own subscriptions can be canceled, providing clear context for when to use this tool. However, it does not explicitly mention alternatives or 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?

The description adds significant context beyond the annotations: it lists the return values (verdict, structured form, actual value with citation, percent delta) and reveals the data sources (SEC EDGAR + XBRL). All annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint) are consistent with the description.

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

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

The description is moderately concise, starting with example queries and then stating usage, domain, and return format. It is front-loaded with key phrases, though a few sentences could be merged for brevity.

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 compensates by detailing the return values and data sources. It covers purpose, usage, domain, and behavioral details, making it complete for a single-parameter tool.

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

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

With 100% schema description coverage, the parameter 'claim' is already well-documented. The description provides example claims, which adds marginal value. 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 verifies natural-language claims against authoritative sources, specifically company-financial claims, using SEC EDGAR and XBRL. It provides example use cases ('fact check', 'verify the claim') and distinguishes it from sibling tools by being a specialized fact-checker for financial data.

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

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

The description explicitly advises to use the tool when the agent needs to check factual correctness, and it specifies the domain (company-financial claims). It mentions that it replaces multiple sequential calls, indicating efficiency. While it doesn't explicitly state when not to use it, the domain restriction is clear enough.

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