Lens Org

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

Annotations indicate read-only, idempotent, and non-destructive. Description adds behavioral details: returns per-model score, confidence, signals, raw_response, and combined view. Discloses external API calls when Anthropic key is provided and payment responsibility.

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: first sentence defines core purpose, second explains key configuration, third describes return structure and use cases. Front-loaded and no wasted words.

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

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

No output schema, but description outlines return structure (per-model object with score/confidence/signals/raw_response plus combined view). Covers all necessary operational details for a probe tool. Schema coverage 100% helps completeness.

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

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

Schema coverage is 100%. Description adds concrete examples for entity (e.g., 'Pipeworx'), explains models parameter with supported values, clarifies _apiKey usage, and describes context for disambiguation. Significantly enhances 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 probes LLMs for knowledge and returns a visibility score (0-100) per model. It specifies verb (probe), resource (LLMs), and outcome (score). Distinguishes from siblings by focusing on LLM probing and scoring.

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

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

Provides explicit guidance on default model vs using Anthropic with API key. States usefulness for AI-marketing audits, pre-launch checks, and monitoring. Lacks explicit comparison with sibling tools but gives sufficient context for usage.

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

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

Annotations indicate readOnly, openWorld, idempotent, non-destructive. The description adds context about routing to 3,547 tools and returning citation URIs. No contradiction with annotations.

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

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

The description is detailed and front-loaded with purpose, but it is somewhat lengthy. Every sentence adds value, but it could be 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?

Given the complexity (3,547 tools) and rich annotations, the description fully explains the tool's meta-search behavior and scope. It is complete enough for an agent to decide when to invoke it.

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 each alias. The description does not add significant meaning beyond the schema, hence baseline 3 is appropriate.

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

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

The description clearly specifies the tool's purpose: it routes questions to a vast set of verified tools for authoritative structured data. It explicitly contrasts with web search, making its unique value clear.

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

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

The description explicitly states 'PREFER OVER WEB SEARCH' and provides extensive examples of when to use (e.g., SEC filings, FDA data, economic stats). It does not explicitly state when not to use, but the guidelines are strong.

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

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

The description adds significant behavioral details beyond annotations, such as costing one extra LLM call, returning specific refusal reasons (not_in_source, no_tool_match, tool_error, data_truncated, llm_error), and using only tool result content. Annotations already indicate readOnly, openWorld, idempotent, and non-destructive, and description aligns perfectly.

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

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

The description is a single paragraph of about 120 words, front-loading the key purpose. Every sentence contributes meaning, though it could be slightly more concise. Efficient for the complexity.

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

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

For a complex tool involving multi-step routing and grounded extraction, the description covers behavior, output structure (answer, evidence, confidence, source, fetched_at, refusal_reason), failure modes, and cost trade-offs. No output schema exists, but description compensates fully.

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

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

Schema coverage is 100%, so baseline 3. Description adds value by listing aliases (query, q, prompt, text, input) beyond what schema shows, clarifying parameter usage.

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

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

The description clearly states the tool is a 'Hallucination-resistant answer mode for high-stakes reads' and specifies it 'EXTRACTS the answer using ONLY what the tool result contains'. This distinguishes it from sibling 'ask_pipeworx' by emphasizing grounded, evidence-based answers.

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

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

Explicitly provides when-to-use: 'whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts'. Also advises against casual use: 'prefer ask_pipeworx for casual lookups'.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description far exceeds this by detailing resolution logic, fan-out patterns, response shapes (market, analysis, evidence fields), safety mechanisms (low-confidence short-circuit, closed market handling), and edge cases (fallback, illiquid spreads). Every behavioral trait essential for safe invocation is disclosed.

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

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

The description is long but front-loaded with the core purpose and structured into readable sections (classifiers, fan-out examples, response shapes, safety). Every section adds necessary detail for a complex tool. Minor wordiness in places, but still effective. Scores 4 for being slightly verbose yet well-organized.

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

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

No output schema exists, so the description carries full responsibility for explaining return values. It does so comprehensively: details result.market, result.analysis, result.evidence, resolver contract fields, parent_event, news fields, and status codes. It covers all critical scenarios (low confidence, closed markets, illiquid spreads). Extremely 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?

With 100% schema description coverage, baseline is 3, but the description adds significant value: it gives examples for market_input (slug, URL, question text), explains depth default and quick vs. thorough, and provides size/usage guidance for include_raw. It also clarifies the implications of defaults (e.g., 'recommended' for false). This goes well 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 starts with a clear verb+resource: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies the input types (slug, URL, question text) and the output (evidence packet + comparison), distinguishing it from sibling tools like polymarket_edges or ask_pipeworx by focusing on single-bet research with Pipeworx data integration.

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

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

The description explicitly states when to use: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It provides contextual examples but does not mention when not to use or suggest alternative sibling tools. This is clear context without exclusions, earning a 4.

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

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

Annotations (readOnlyHint=true) are consistent, and the description adds context on data sources (SEC EDGAR/XBRL, FAERS), sorting by primary metric, and citation URIs. No contradictions; the description enriches behavioral understanding.

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

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

The description is dense but front-loaded with example triggers. Every sentence serves a purpose, though it could be slightly more concise by trimming some examples. 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?

Despite no output schema, the description explains return format (paired data + citation URIs) and sorting behavior. For a two-parameter tool with clear use cases, it is fully complete and leaves no critical gaps.

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

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

With 100% schema coverage, the description still adds significant meaning: it explains what each 'type' entails (company vs. drug) and specifies the format for 'values' (tickers/CIKs or drug names). This goes well beyond the schema constraints.

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 side-by-side comparisons of 2-5 companies or drugs in one call, with specific examples of natural language triggers. It distinguishes this from sequential lookups, making its purpose unambiguous.

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

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

It explicitly advises 'ALWAYS PREFER over sequential single-pack lookups when comparing entities,' providing a strong usage directive. However, it lacks explicit when-not-to-use scenarios beyond that.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true. The description adds that it returns top-N most relevant tools with full input schemas and curated examples, and that results are ready to call directly without a second schema lookup. This goes beyond annotations, providing useful behavioral insight.

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 concise sentences, no wasted words. The first sentence immediately states the purpose, and the body adds usage guidance and return details efficiently.

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

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

For a discovery tool with no output schema, the description adequately explains the return format (top-N, ready to call). It could briefly mention pagination or how results are ordered, but overall it is sufficiently complete for the tool's complexity.

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

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

Schema description coverage is 100%; all parameters have descriptions, including alias relationships. The description adds value by listing example queries (e.g., 'look up FDA drug approvals'), but does not add meaning beyond the schema for individual parameters. Baseline 3 is appropriate.

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

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

The description clearly states the tool finds tools by describing data or task, with a specific verb ('find') and resource ('tools'). It lists many example domains (SEC filings, FDA drugs, etc.), which distinguishes it from sibling tools that are specific tools.

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

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

Explicitly advises calling this tool first when many tools are available and the agent wants to see the option set, not just one answer. The list of example use cases provides clear context, though it does not explicitly say when not to use it.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false. The description adds valuable behavioral context: parallel fan-out across sources, patent API sunset soft-fail, GDELT→GNews fallback, and specifics on returned fields. No contradictions.

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

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

The description is front-loaded with example queries and includes necessary details. While somewhat lengthy, every sentence adds value. Minor redundancy could be trimmed, but it's 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 enumerates return fields and data sources, including fallbacks and limitations. It provides enough completeness for an agent to understand the tool's behavior.

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

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

Schema coverage is 100% and parameters are already described. The description adds meaning by clarifying that value can be a ticker or zero-padded CIK, and that names are not supported, which goes beyond schema documentation.

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

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

The description clearly states the tool's purpose as a 'full cross-source profile of a US public company' and provides example user queries. It distinguishes itself from chaining single-pack lookups by emphasizing a single parallel call.

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 instructs to prefer this tool over chaining individual lookups for holistic views, and notes that names are not supported (use resolve_entity first). This 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 provide destructiveHint=true and idempotentHint=true. Description adds context about clearing sensitive data and use cases, aligning with 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?

Two sentences with no fluff, front-loaded with action and resource, followed by usage guidelines and pairing advice.

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

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

With only one parameter, no output schema, and annotations covering destructive and idempotent behavior, the description fully covers purpose, usage, and pairing, leaving no gaps.

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

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

Single parameter 'key' with description in schema is clear. Schema coverage is 100%, so description doesn't need to add more; baseline score of 3 is appropriate.

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

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

Description clearly states 'Delete a previously stored memory by key', with a specific verb and resource. It distinguishes from siblings 'remember' and 'recall' by indicating deletion.

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

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

Explicitly describes when to use: 'when context is stale, the task is done, or you want to clear sensitive data'. Also suggests pairing with remember and recall.

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 process: fetches the page, extracts title/description/key links, and emits standard markdown format. Annotations already indicate read-only, open-world, idempotent, and non-destructive behavior, and the description does not contradict them.

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

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

The description is concise (three sentences) and front-loaded with the primary purpose. Every sentence is informative and there is no redundant or extraneous information.

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

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

For a tool with two simple parameters, full annotations, and no output schema, the description is complete. It explains the output format, use cases, and behavioral process, leaving no significant gaps for an AI agent to understand how and when to use the tool.

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

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

Schema coverage is 100% (both parameters are documented in the schema). The description does not add significant meaning beyond the schema; it implies url and max_links but does not elaborate on parameter usage or constraints beyond what is already in the input 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 that the tool generates an llms.txt file for a given URL, specifying the output format and use cases. It uses specific verbs and resource ('Generate a production-ready llms.txt file for any URL') and distinguishes from any sibling tools by focusing on a unique function.

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

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

The description explicitly lists when to use the tool: for getting a client's site indexed by AI, drafting llms.txt for a project, or auditing competitor's AI visibility. It provides clear context but does not mention when not to use or alternative tools.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds minimal behavioral context by listing return fields and the include_inactive parameter, but does not disclose potential rate limits or other traits. No contradiction.

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

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

The description is two sentences, each earning its place. The first sentence states the purpose and return fields, and the second provides usage guidance. No wasted words.

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

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

Given the tool's simplicity (one optional parameter, no complex output schema), the description is complete. It tells the agent what it does, when to use it, and what it returns. Sibling tools are different enough that no further disambiguation is 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?

The schema covers 100% of parameters, so the description does not need to add much. It mentions the include_inactive parameter effect, but this is already described in the schema. Baseline 3 is appropriate.

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

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

The description clearly states that the tool lists the caller's active subscriptions, specifying the verb (list) and resource (subscriptions). It differentiates from sibling tools like subscribe and unsubscribe by clarifying the action.

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

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

The description provides explicit use cases: to review what you're monitoring before adding more or to find an id to cancel. It does not explicitly state when not to use it or mention 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?

Annotations already provide readOnlyHint, idempotentHint, openWorldHint, and destructiveHint false, fully covering the safety profile. The description adds no behavioral context beyond the basic operation, such as rate limits or output details, which is acceptable given annotation coverage.

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?

Extremely concise at 4 words, but lacks front-loading of essential context. Every word earns its place, though it could be slightly more informative without becoming verbose.

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

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

Given the tool's simplicity, an output schema exists, and annotations are comprehensive, the minimal description is adequate. However, it fails to explain what the output contains or the nature of 'lens_id', leaving minor gaps in completeness.

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

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

Schema coverage for parameters is 0%, but the description adds no meaning to 'lens_id'. The example in the schema helps, but the description itself does not clarify the parameter's format or constraints, leaving the agent without added value.

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

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

The description explicitly states the resource (Single patent) and identifier (lens_id), clearly distinguishing from sibling 'patents_search' which is for searching. The verb is implied (get/fetch) but unambiguous given context.

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

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

No guidance on when to use this tool versus alternatives like 'patents_search'. The description lacks any context about appropriate use cases or exclusions.

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

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

The annotations already declare the tool as read-only, open-world, idempotent, and non-destructive. The description adds no behavioral context beyond that, such as what results are returned, pagination, or rate 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 (one sentence) but lacks informational value. It essentially restates the tool name, wasting the opportunity to provide useful guidance.

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

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

Given the tool's moderate complexity (3 parameters, output schema present), the description is insufficient. It fails to explain the query format, result structure, or any constraints beyond what the schema provides.

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 67% (2 of 3 parameters have descriptions). The tool description 'Patent search.' adds no parameter explanations or usage hints, leaving the undocumented 'from' parameter without context.

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

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

The description 'Patent search.' clarifies the tool's purpose as searching patents, which is slightly more specific than the name 'patents_search'. However, it remains vague and does not differentiate from siblings like 'patent' (which likely retrieves a single patent) or 'scholarly_search'.

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 usage guidelines are provided. The description does not indicate when to use this tool versus alternatives like 'patent' for specific patent lookup or 'scholarly_search' for scholarly articles.

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

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

The description adds substantial behavioral context beyond the annotations: rate-limited to 5 per identifier per day, does not count against tool-call quota, free to use, and that the team reads digests daily. Annotations are all false and the description is consistent.

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 yet comprehensive, with clear front-loading of the core purpose. Every sentence adds value, and the structure is logical and easy to parse.

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

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

Given no output schema, the description explains what happens (team reads digests, signal affects roadmap) and covers rate limits and quota. For a feedback tool, this provides complete contextual information for the agent.

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

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

Schema coverage is 100%. The description adds meaning by explaining the enum values (bug, feature, data_gap, praise, other) and advising to be specific in the message. It also notes that context is optional, adding value beyond the schema.

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

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

The description clearly states the tool is for giving feedback ('Tell the Pipeworx team something is broken, missing, or needs to exist'), specifies the types of feedback (bug, feature/data_gap, praise), and distinguishes from siblings by being a feedback mechanism.

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

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

The description explicitly states when to use the tool (bug, feature, data_gap, praise) and provides guidance on what not to do ('don't paste the end-user's prompt'). It also mentions rate limits and that it's free. However, it does not explicitly compare with alternative tools for similar purposes.

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?

While annotations already mark readOnly and idempotent, the description adds caching behavior (5min-1h), data source (CF analytics-engine), no PII, and the aggregated fields (pack, tool, count). No contradiction with annotations.

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

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

The description is front-loaded with the main result, then use cases, then technical details. It is slightly verbose but each sentence adds value. Could be tightened, but not a significant issue.

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

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

For a simple tool with one parameter and rich annotations, the description covers purpose, usage, behavioral details, and parameter semantics. No output schema exists, but the description compensates by describing the return format implicitly.

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

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

The single parameter 'window' has an enum and description in the schema. The description adds context for each window's purpose (shorter for hot, longer for steady-state), going beyond the schema.

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

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

The description clearly states it returns top tools, packs, and call volume over a window, with three specific use cases. It distinguishes from sibling tools like discover_tools by focusing on popularity.

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 three 'Useful for' bullets provide explicit guidance on when to use this tool, covering discovery, canonical choice confirmation, and alignment checking. It lacks explicit when-not-to-use or alternatives, but context is clear.

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

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

Annotations indicate readOnly, openWorld, idempotent, non-destructive. The description adds behavioral details: parameter requirement, Jaccard similarity threshold, partition filter logic, and response structure including partition_check deviation threshold, all beyond what annotations provide.

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

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

The description is well-structured and informative, but slightly verbose with detailed explanations of internal logic. While all sentences add value, some could be tightened for conciseness 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 explains the response structure (opportunities array with fields and partition_check object) and covers failure cases (no args, similarity filter, placeholder filter). It is fully complete for understanding tool behavior.

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

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

Schema coverage is 100% with descriptions. The description adds value by explaining the format of slugs, acceptance of full URLs, and concrete examples for both parameters, enhancing understanding 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's purpose: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It distinguishes between single-event and cross-event modes with concrete examples and differentiates from sibling tools like polymarket_edges by focusing on arbitrage detection.

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 requires one of `event` or `topic` and warns that calling with no args fails. It recommends when to use each mode, explains the semantic anchor and partition filter, and notes what cross-event mode catches that single-event mode misses.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description goes far beyond by detailing the three model families, their formulas (e.g., partition_overround with sport-specific α), the per-opportunity fields (edge_pp_net, kelly_fraction), and diagnostics like funnel counters. It also mentions caching at 1h KV level. 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 lengthy (~500 words) and dense, but it is logically structured with clear sections (MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, etc.) and front-loaded purpose. While effective, it could be trimmed for easier parsing, but the complexity justifies the length.

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

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

Given 9 parameters and no output schema, the description fully explains the response structure (by_segment, diagnostics, Fed candidates) and provides filters (placeholder-slug, >20% placeholder fraction skipped) and knob interactions. It covers edge cases and caching, making it complete for an agent to use correctly.

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

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

Schema description coverage is 100% (all 9 parameters have descriptions). The description adds extra nuance, e.g., explaining that min_partition_leg_kelly applies to per-leg Kelly within partitions, and that slippage_pp is subtracted before ranking. This complements the schema without redundancy.

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

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

The description clearly states the tool scans top Polymarket markets and returns opportunities where Pipeworx data disagrees with market price, specifically for betting discovery. It distinguishes itself from siblings like polymarket_arbitrage by focusing on proprietary data and detailed model families.

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

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

The description explicitly states the use case ('what should I bet on today') and explains when to adjust knobs like min_liquidity and max_spread_pp for tradeable edges. It also notes that Fed bets are excluded from ranking. However, it does not directly advise when not to use or compare with sibling tools.

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

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

Annotations already indicate readOnly, openWorld, idempotent, and non-destructive hints. The description adds substantial behavioral context: it details compatibility_warning conditions (non-equivalent bet shapes, semantically unrelated events), temporal_alignment, skipped_cross_type/subtype counters, and the fact that spreads are mathematically meaningless if not aligned. This goes well beyond annotations with no contradiction.

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

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

The description is front-loaded with the core purpose and modes, but it is quite verbose, running several sentences. While well-structured with bolded key terms, it could be more concise while retaining essential information.

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

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

Given the absence of an output schema, the description thoroughly explains the response structure (leg-by-leg prices, matched spreads, safety fields, compatibility_warning conditions, temporal alignment, skipped counters). It covers scenarios and edge cases, making it complete for an agent to understand the tool's behavior and output.

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 three parameters have descriptions in the schema (100% coverage). The description adds value by explaining the two modes in detail and providing examples of how to use each parameter. It also clarifies that explicit parameters override topic-mapped ones.

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 computes cross-venue spreads between Kalshi and Polymarket for the same resolving question, with explicit mention of two modes (topic and explicit). This distinguishes it from sibling tools like polymarket_arbitrage, which may focus on intra-platform 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 explains when to use the tool (to compute spreads and check compatibility) and outlines two modes with examples. It warns that most pre-mapped topics return compatibility warnings, hinting at when the tool may not be useful. However, it lacks explicit statements about when NOT to use it or alternatives.

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

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

Annotations already declare readOnly, idempotent, non-destructive. Description adds scoping ('by identifier') and relationship to remember/forget, going 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 concise sentences, front-loaded with action and purpose. 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?

Fully covers purpose, usage, scoping, and tool relationships for a simple retrieval tool with one parameter and no output schema.

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

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

Single optional parameter with schema description matching tool description. No additional semantic enrichment beyond what schema provides.

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

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

Clear verb ('retrieve' or 'list') and resource ('saved memory'). Distinguishes from sibling 'remember' and 'forget' by specifying retrieval and listing behavior.

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 state when to use ('look up context...without re-deriving') and when to omit key (to list all). Lacks explicit 'when not to use', but sibling set provides 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?

Despite annotations indicating readOnlyHint and destructiveHint false, the description transparently explains that setting mark_read:true flags events as read, affecting future calls. This side effect is disclosed, adding value beyond annotations.

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

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

The description is concise and front-loaded with the main purpose. Every sentence adds value—purpose, return fields, filtering, mark_read behavior, and alternative endpoint—with no redundancy or fluff.

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

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

With no output schema, the description adequately covers return fields and explains the effect of mark_read. It mentions polling and alternative access, providing sufficient context for a tool with five optional parameters and no required inputs.

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

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

Schema description coverage is 100%, so the schema already documents each parameter. The description summarizes filtering options and provides an example (e.g., 'sec_8k'), but does not add significant new meaning beyond the schema.

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

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

The description clearly states 'Pull fired events from your subscription feed' and specifies the return fields (source, citation_uri, raw event payload). It distinguishes itself from sibling tools like list_subscriptions by focusing on reading alerts rather than managing subscriptions.

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

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

Provides specific guidance on filtering by type and timestamp, using mark_read for subsequent calls, and mentions polling suitability. It also points to an alternative GET endpoint for scripts/dashboards, helping users decide when to use this tool versus the direct URL.

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

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

Beyond annotations (readOnlyHint, etc.), the description discloses parallel fan-out to multiple sources, fallback logic for GDELT to GNews, and soft-fail for USPTO due to API sunset. It also describes the output format (grouped changes, count, citation URIs), providing rich behavioral context.

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

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

The description is a compact, information-dense paragraph. It front-loads example queries, then systematically lists sources, parameter details, outputs, and sibling guidance. Every sentence is essential and efficiently conveys critical information without redundancy.

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

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

Given the tool's complexity (multiple sources, fallback, soft-fail, no output schema), the description fully covers all aspects: input parameters, behavior, output structure (grouped changes, total_count, citation URIs), and clear guidance on when to use the sibling tool. No gaps remain.

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

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

With 100% schema coverage, the description adds significant value: clarifies 'since' accepts ISO dates or relative shorthand with examples ('7d', '30d', '1y'), notes 'type' only supports 'company', and gives 'value' examples (ticker or CIK). This far surpasses 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 as a change feed for a company in a specified time window, listing specific sources (SEC, GDELT/GNews, USPTO) and output structure. It distinguishes from the sibling tool 'entity_profile' by advising to use that for static profiles.

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

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

Explicit usage context is provided with example queries ('What's new with X', 'latest on Y'). It specifies when to use this tool versus 'entity_profile', explains fallback behavior (GDELT→GNews), and notes USPTO's soft-failure, guiding appropriate selection.

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

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

Annotations provide idempotentHint=true and no destructiveness. Description adds persistence details: authenticated users get persistent memory, anonymous sessions retain 24 hours. No contradictions.

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

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

Four sentences, each adding unique value: purpose, usage, storage details, retrieval pairing. No wasted words.

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

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

Given simple 2-param tool with no output schema, description covers purpose, usage, persistence, and sibling relationships. Agent can use correctly.

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

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

Schema has 100% coverage with descriptions. Description adds usage examples and clarifies purpose beyond schema, like 'key-value pair' and examples for key.

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 'Save data the agent will need to reuse later' with specific resource 'key-value pair scoped by your identifier'. Distinguishes from siblings 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'. Pairs with recall and forget. Missing explicit 'when not to use' but context is sufficient.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds behavioral context: it cascades through several lookup endpoints internally, replaces 2-3 manual lookups, and returns specific fields with citation URIs. This exceeds the annotation burden 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 a single, well-structured paragraph with no wasted words. It front-loads the core purpose with examples, then details supported types and outputs. 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 having no output schema, the description fully explains what each entity type returns, including fields and citation URIs. It mentions internal cascading and the efficiency gain. With 2 required parameters and 100% schema coverage, the description provides complete guidance 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% for both parameters, but the description adds substantial meaning: for 'type', it explains what each enum value returns (e.g., company returns ticker, CIK, name, and citation; drug returns RxCUI, ingredient, brand). For 'value', it provides examples and notes auto-disambiguation. This significantly enhances schema 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's purpose: resolving a user-spoken name to a canonical/official identifier. It provides specific query examples ('What's the ticker for...', 'find the CIK for...') and explicitly lists supported entity types (company, drug). The phrase 'Use FIRST whenever you have a name but need an ID' distinguishes this tool from siblings that likely require IDs as input.

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

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

The description gives clear when-to-use guidance: 'Use FIRST whenever you have a name but need an ID.' It does not explicitly state when not to use or provide alternatives, but the context implies that if the ID is already known, this tool is unnecessary. The directive 'FIRST' indicates priority in multi-step workflows.

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

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

Annotations already declare readOnly, idempotent, non-destructive. Description adds that it probes each entity by calling ai_visibility_check, ranks results, and returns a ranked list with score, confidence, signal density. Also notes first entity is treated as subject. Provides context beyond annotations.

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

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

Two sentences with zero waste. First sentence states purpose and method; second sentence gives use case and output. Front-loaded and efficient.

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

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

Given 4 parameters (1 required) and no output schema, description explains returned data (ranked list with score, confidence, signal density) and mentions internal call to ai_visibility_check. Complete for a wrapper tool, though could mention potential limitations like rate limiting.

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. Description adds meaningful context: default model (workers-ai), requirement of _apiKey for anthropic, first entity as subject, context as shared disambiguator. Enhances schema without redundancy.

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

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

Description clearly states tool compares AI visibility across multiple entities side-by-side, with specific verb 'probes' and ranking. It differentiates from sibling tools like ai_visibility_check (single entity) and compare_entities (general 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?

Explicit use case provided: 'competitive AI-marketing audits'. Implies when to use (comparing multiple entities) but does not explicitly state when not to use or list alternative tools.

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

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

Beyond annotations (readOnly, idempotent), the description discloses bundlephobia's 5-30s first measurement delay, graceful partial failures with 'sources_failed' field, and the fan-out architecture. 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?

Efficiently front-loads the core action, then details usage, caveats, output fields, and limitations. Slightly long but no wasted sentences.

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

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

Despite no output schema, the description enumerates return fields, explains partial failures, and covers ecosystem constraints. Fully sufficient for agent decision-making.

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

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

Schema coverage is 100%, but description adds value by explaining scoped package format and version default behavior. This meaningfully supplements the schema.

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

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

The description clearly states it's a composite check for npm packages, covering safety, popularity, and size via deps.dev and bundlephobia. It distinguishes itself from siblings by specifying the unique combined analysis scope.

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

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

Explicitly states when to use: for questions like 'is X safe / popular / small' or 'what does adding lodash cost me'. Also clarifies NPM-only in v1 and provides fallback for other ecosystems, helping agents choose correctly.

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

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

Annotations provide readOnlyHint, idempotentHint, etc., so the safety profile is clear. The description adds no behavioral detail (e.g., error handling, scope) but also contradicts nothing. It meets the minimum given annotation coverage.

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?

Extremely concise (4 words), but lacks essential information. Conciseness is not valuable when it omits purpose and usage. Not sufficiently structured to be helpful.

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 having an output schema, the description is too minimal. It doesn't cover what the tool does, when to use it, or parameter meaning. For a simple 1-parameter tool, the description is still incomplete.

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 0%, yet the description provides zero parameter explanation. The lone parameter 'lens_id' is not described; only an example exists. The description fails to compensate for the missing schema descriptions.

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

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

The description 'Single scholarly work' is vague. It doesn't specify the action (e.g., retrieve, fetch) and the name 'scholarly' alone is unclear. The purpose is implied but not clearly stated, making it hard for an agent to distinguish from 'scholarly_search'.

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

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

No guidance on when to use this tool versus alternatives like 'scholarly_search'. There is no mention of prerequisites, context, or when not to use it. The agent gets no decision support.

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 cover safety and idempotency (readOnly, openWorld, idempotent, non-destructive), but description adds zero behavioral context beyond that.

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

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

Single sentence is concise but under-specified. It earns its place by stating purpose, but lacks helpful structure.

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

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

Despite having output schema, description is too sparse for a 3-parameter tool with 0% schema description coverage. No differentiation from siblings.

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 0%, so description should compensate. It mentions 'search' but does not explain any parameter meaning, format, or constraints.

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

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

Description clearly states the tool searches scholarly works, with a specific verb and resource. However, sibling includes 'scholarly' without suffix, lacking differentiation.

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

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

No guidance on when to use this versus alternatives like 'scholarly' or other search tools. No context for prerequisites or exclusions.

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

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

Beyond annotations (readOnlyHint, etc.), the description discloses key behaviors: 200K char truncation with flag, BGE-base-en embeddings, 500-char overlapping windows, cosine similarity, and passage offsets for verification.

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

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

Front-loaded with purpose, then use case, then technical details. Every sentence adds value without redundancy or fluff.

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

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

Covers input cap, output features (passages, offsets, scores), and embedding details. Lacks explicit output structure but given no output schema, the description provides sufficient guidance for understanding expected results.

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 high. Description adds helpful query examples and clarifies the text parameter's truncation behavior, providing richer context than schema alone.

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

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

The description clearly states the tool performs semantic search inside a fetched record, with concrete examples (SEC 10-K body, article). It distinguishes itself from sibling ask_pipeworx_grounded by specifying 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?

Explicitly says when to use: 'Use when the record is too big to cram into the prompt.' Also mentions when not to use direct alternatives and pairs with ask_pipeworx_grounded for grounded generation.

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

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

Annotations indicate mutation (readOnlyHint=false) and idempotency (idempotentHint=true). Description adds OAuth requirement, type examples, delivery channel behaviors, and SMS limit. 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 paragraph, front-loaded with purpose, then requirements, then types with examples, then delivery. No wasted words; 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?

Covers creation, auth, types, delivery, and response. No output schema, but states returns subscription id. Lacks mention of duplicate handling (idempotency makes safe). Adequate for subscription tool.

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

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

Schema coverage 100% but description adds significant detail: examples per type (e.g., items:['5.02'] for sec_8k), format requirements (E.164 for SMS), and caveats (patent_grant match approximate). 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?

Description clearly states the verb 'create', resource 'proactive monitoring subscription', and output 'returns the new subscription id'. It lists supported types, distinguishing it 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?

States requirement for Pipeworx OAuth account and that anonymous/BYO cannot persist. Explains delivery channels and SMS cap. Could be more explicit about when not to use (e.g., for one-time checks), but provides clear context for proactive monitoring.

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, describes deactivation behavior and why it's not destructive ('row is deactivated (not deleted) so its historical events stay available via recent_alerts').

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 tight sentences, front-loaded with action, no wasted words.

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

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

Fully adequate for a one-parameter tool with good annotations; covers purpose, ownership, and side effects.

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?

Single parameter 'id' with schema coverage 100%; description adds minimal value beyond schema by referencing 'subscribe' as source of the id.

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+resource ('Cancel a subscription by id') and distinguishes from sibling 'subscribe'.

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?

States ownership enforcement ('you can only cancel your own subscriptions'), providing clear usage guidance, though no explicit alternative tools mentioned.

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

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

Annotations already indicate readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds value by detailing the return format (verdict types, structured form, actual value with citation, percent delta) and source (SEC EDGAR + XBRL), providing behavioral context beyond annotations. No contradictions.

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

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

The description is concise yet comprehensive, front-loading the core purpose and examples. Every sentence adds value, and it efficiently communicates the tool's capabilities without extraneous 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?

Despite no output schema, the description fully explains the return values (verdict, structured form, citation, delta). It covers the tool's scope, limitations (company-financial claims for US public companies), and efficiency benefits, making it complete for the tool's complexity.

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

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

Schema coverage is 100% with a single 'claim' parameter described as natural-language factual claim. The description adds value by providing concrete examples (e.g., "Apple's FY2024 revenue was $400 billion"), which enhances understanding beyond the schema.

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

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

The description clearly states the tool's purpose: natural-language claim verification against authoritative sources, specifically for company-financial claims. It includes example usage patterns (e.g., 'verify the claim that...') which distinguish it from sibling tools like compare_entities or resolve_entity.

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

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

The description explicitly states when to use the tool: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also specifies the supported domain (company-financial claims for public US companies) and explains it replaces multiple sequential calls, providing clear usage context.

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