Trademarks

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

Annotations already declare readOnlyHint, idempotentHint, etc. The description adds value by disclosing the return format (per-model fields + combined view) and the cost implication ('you pay Anthropic directly'). 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?

Four sentences, front-loaded with the core purpose, then providing critical details (default model, cost, return format) without redundancy. Every sentence earns its place.

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

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

Given no output schema, the description adequately explains the return structure (per-model and combined view). The tool has moderate complexity (4 params, no enums), and the description covers essential behavior for an agent to invoke it correctly.

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

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

Schema description coverage is 100%. The description adds meaning beyond the schema by explaining the default model, the purpose of _apiKey (BYO key for Anthropic), and the role of context for disambiguation. This compensates for any lack of enum values or nested object hints.

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

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

The description uses a specific verb ('Probe') and clearly identifies the resource ('LLMs for what they know about a business / brand / product / topic'), with a concrete outcome (visibility score 0-100). It distinguishes this tool from siblings like ask_pipeworx or compare_entities by focusing on multi-model AI visibility scoring.

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

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

The description explicitly lists use cases ('AI-marketing audits, pre-launch brand checks, competitive monitoring') and provides conditional usage details (default model vs. Anthropic with _apiKey). It does not explicitly state when to avoid the tool, but the context is clear enough for an agent to decide.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive behavior. The description adds value by explaining internal routing to 3,751 tools and that output includes stable citation URIs ('pipeworx://'), which goes 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 moderately long but efficiently front-loaded with the key instruction 'PREFER OVER WEB SEARCH'. Each sentence adds value, covering domains, mechanism, usage triggers, and examples. Minor redundancy (e.g., repeated 'current') 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 the tool's complexity as a query router, the description provides comprehensive context: purpose, when to use, how it works internally (routing, filling arguments), and output format (citation URIs). No output schema, but the description compensates well.

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

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

Schema description coverage is 100%, with all parameters documented as aliases for 'question'. The description adds examples and usage context but does not significantly expand parameter meaning beyond 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 the tool's purpose: answering factual questions using structured data from 3,751 tools across 886 sources. It explicitly distinguishes from web search and lists specific domains (SEC filings, FDA data, etc.), leaving no ambiguity about its 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 provides extensive usage guidance: 'PREFER OVER WEB SEARCH', concrete query types ('what is', 'look up', 'find', etc.), and domain examples. It implicitly advises when to use this tool over siblings, and the sibling list includes many specialized tools, making the preference 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, including the extra LLM call cost, the structured return format with answer, evidence, confidence, source, fetched_at, and refusal_reason, and the explicit refusal reasons (not_in_source, no_tool_match, etc.) that occur when data doesn't directly answer.

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 a concise purpose statement and includes structured details like return format and refusal reasons. It is slightly long but every sentence adds value, making it appropriately sized for the tool's complexity.

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

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

Given no output schema, the description comprehensively explains the return structure, refusal reasons, and usage context. It covers all necessary aspects for the agent to correctly select and invoke the tool, including cost trade-off and behavioral guarantees.

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

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

Schema coverage is 100%, so the baseline is 3. The description mentions that the question parameter accepts multiple aliases, which is already in the schema, and adds minimal additional semantic value beyond what the schema provides.

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

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

The description clearly identifies the tool as a 'hallucination-resistant answer mode for high-stakes reads,' specifies it routes identically to ask_pipeworx but extracts answer only from tool result, and differentiates it from its sibling by stating when it should be used.

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

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

Explicitly states when to use: 'whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts' and when not to: 'prefer ask_pipeworx for casual lookups,' naming the alternative directly.

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

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

The description discloses extensive behavioral details: fan-out logic per category, resolver contract with confidence levels, parent event extraction, news fallback handling, safety short-circuits for low-confidence matches and closed markets, wide spread warnings, and resolution rule risk. This goes far beyond the annotations (which already indicate read-only, idempotent, non-destructive) and adds critical 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 thorough but overly long and dense, with multiple sections (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, etc.). It is structured with headers, but each sentence could be more concise. The front-loaded purpose is good, but the verbosity reduces overall conciseness.

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

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

Given the complexity of the tool (3 parameters, multiple fan-out paths, various response sections and edge cases), the description is remarkably complete. It covers low-confidence matches, closed markets, wide spreads, resolution rules, and return shape details. No output schema exists, so the description fully 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% with good descriptions for all three parameters. The description adds value by explaining the market parameter input types (slug, URL, question text), the effect of depth (quick vs thorough fan-out), and include_raw (summary vs full payloads). This 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 researches a Polymarket bet by pulling Pipeworx data. It specifies the inputs (market slug, URL, question text) and outputs (evidence packet, market-vs-model comparison). It distinguishes itself from sibling tools by focusing specifically on bet research and data fan-out.

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

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

The description explicitly tells when to use the tool ('should I bet on X', 'what does the data say about Y', 'is there edge in Z') and provides examples. It lacks explicit when-not-to-use guidance or alternatives, but the context is clear enough from the sibling list and the tool's purpose.

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

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

The description adds significant behavioral context beyond annotations, including data sources (SEC EDGAR/XBRL, FAERS), handling of off-calendar fiscal years, and return of citation URIs. No contradictions with annotations.

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

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

The description is front-loaded with example queries and key usage, but is somewhat lengthy. Every sentence adds value, though more conciseness could improve 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?

Given no output schema, the description fully explains return format (paired data + citations), data sources, sorting, and entity limits. It is complete for an 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%, so baseline is 3. The description provides extra meaning by explaining parameter values (tickers/CIKs for company, names for drug) and data behavior (sorting by primary metric), enhancing schema definitions.

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

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

The description clearly states the tool performs side-by-side comparisons of 2-5 companies or drugs in one call, with explicit verbs and resources. It distinguishes from sequential single-pack lookups, making purpose unambiguous.

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

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

The description explicitly advises preferring this tool over sequential lookups for comparisons and lists example query phrases. However, it does not detail specific exclusions or alternative tools by name, slightly limiting 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?

Beyond annotations (readOnly, openWorld, idempotent, non-destructive), the description details parallel execution, verbatim evidence with citations, explicit gaps for unanswered facets, and no invented facts. Also discloses account and plan requirements.

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 fairly long but each sentence adds distinct value—purpose, process, output, usage guidance, and requirements. It front-loads the core purpose. Minor redundancy (e.g., 'pre-verified' could be implied) 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?

Despite no output schema, the description fully explains the return format (structured findings packet with evidence, confidence, source, fetched_at, citations, gaps) and behavioral traits. All key aspects for agent invocation are covered.

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

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

Input schema covers both parameters with 100% description coverage. The description adds value by explaining depth values (quick=3, standard=5, thorough=8) and clarifying that the question can be broad/natural language, which is not detailed in the schema.

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

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

The description explicitly states the tool performs grounded multi-source research in one call, decomposes questions into sub-questions, and routes to many tools in parallel. It clearly distinguishes itself from sibling ask_pipeworx for single lookups.

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

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

Provides explicit guidance: use for broad/multi-part questions, use ask_pipeworx for single lookups. Also mentions prerequisites (Pipeworx account, paid plan for 'thorough') and expected execution time.

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

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

Annotations declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds that it returns 'top-N most relevant tools with names, descriptions, and full input schemas...each result is ready to call directly,' which discloses the output format and readiness beyond annotations.

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

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

The description is a single paragraph that is efficiently front-loaded with purpose, lists relevant domains, and explains returns. It wastes no words and is appropriately sized for the information needed.

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

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

Given that the schema already covers parameters well and there is no output schema, the description explains the return value (top-N tools with schemas) and usage context ('Call this FIRST...'). It is complete enough for an agent to use correctly.

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

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

Schema description coverage is 100%, so the schema already documents all parameters thoroughly. The description mentions 'query' as a natural language description but does not add significant meaning beyond what the schema provides, hence a baseline 3.

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

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

The description begins with 'Find tools by describing the data or task,' clearly specifying the verb 'find' and the resource 'tools.' It distinguishes from siblings by focusing on tool discovery rather than using 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?

The description states when to use: 'Use when you need to browse, search, look up, or discover what tools exist for...' and 'Call this FIRST when you have many tools available and want to see the option set.' It provides clear context but does not explicitly state when not to use, which prevents a 5.

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, openWorldHint, idempotentHint, destructiveHint. Description adds valuable behavioral details: fans out across five sources, notes patent sunset (soft-fail), mentions fallback mechanisms, and lists specific return fields. 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 usage examples and priority instruction. Contains a detailed list of return fields, which is necessary given no output schema. Each sentence contributes useful information, but the description is relatively long. Still efficient for its 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 thoroughly explains the return envelope: CIK, company_name, recent_filings with URIs, fundamentals, patents (with sunset note), news via fallback, and LEI. Covers edge cases like name resolution dependency and API sunset. Comprehensive for a complex multi-source tool.

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

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

Schema coverage is 100%, so baseline is 3. Description adds substantial value by clarifying the exact formats for 'value' (ticker or zero-padded CIK) with examples, reiterates that names are not supported, and explains the type enum limitation. Raises score above baseline.

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

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

Description starts with clear examples like 'Tell me about X' and states 'full cross-source profile of a US public company in ONE parallel call.' It distinguishes from siblings like resolve_entity (name resolution) and compare_entities, making the purpose unmistakably 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?

Explicitly says 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' Also provides clear input constraints: ticker or CIK, not names, with guidance to use resolve_entity first if only a name is available.

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

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

Annotations already provide destructiveHint=true, idempotentHint=true, readOnlyHint=false. The description adds context about clearing sensitive data, but the core behavioral traits are covered by annotations. No contradiction is present.

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

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

The description is two sentences, with the first stating purpose and the second providing usage guidance. Every sentence adds value, and it is front-loaded with the core action.

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

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

Given the low complexity (one parameter, no output schema) and the presence of annotations, the description adequately covers purpose, usage, and behavioral context. 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?

Schema coverage is 100% with the 'key' parameter described as 'Memory key to delete'. The description does not add new semantics beyond reiterating the schema. Baseline of 3 is appropriate.

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

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

The description clearly states 'Delete a previously stored memory by key', providing a specific verb and resource. It distinguishes from sibling tools like 'remember' and 'recall' by explicitly mentioning pairing, implying a distinct deletion 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 explicitly states when to use the tool: 'when context is stale, the task is done, or you want to clear sensitive data'. It suggests pairing with remember and recall, giving implicit guidance on alternatives. However, it lacks explicit 'when not to use' or exclusion 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?

Discloses key behaviors: fetches the page, extracts title/description/key links, outputs standard llms.txt markdown. Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, and the description adds detailed process 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: first states purpose and audience, second describes method and output, third lists use cases. Concise, front-loaded, no redundant words.

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

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

Despite no output schema, the description explains the output format (markdown, single text blob) and usage location (site-root/llms.txt). Combined with comprehensive annotations and simple parameters, the description is fully 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 covers both parameters (url, max_links) with full descriptions. The description adds general context (fetching the page) but does not enhance parameter-level understanding beyond the schema. Schema coverage is 100%, so 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?

Clearly states the tool generates a production-ready llms.txt file for any URL, specifying the verb (generate), resource (llms.txt), and purpose (AI crawler indexing). Distinguished from sibling tools like ai_visibility_check or scan_competitor_ai_presence which serve different AI visibility functions.

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

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

Provides explicit use cases (client sites, own project, competitor auditing) but does not contrast with sibling tools or specify when not to use. The guidance is clear and contextual but lacks 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. The description adds the behavioral context that a USPTO API key is required for authentication, which goes beyond annotations. No contradictions. Could mention rate limits or further constraints, but sufficient given annotations.

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

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

The description is two sentences, front-loads the main action and results, and includes the authentication requirement. No wasted words; efficient and clear.

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

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

Given the tool's simplicity, existence of an output schema (as indicated in context signals), and comprehensive annotations, the description covers the essential information: what it does, what it returns, and a key prerequisite. No obvious gaps 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%, so baseline is 3. The description adds that `registration_number` is a USPTO registration number, but also states 'Requires USPTO API key' while the schema marks `api_key` as optional (not in required). This slight inconsistency reduces clarity. Otherwise, description adds meaning to parameters beyond schema.

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

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

Description clearly states the tool looks up a US trademark by registration number and lists returned fields (status, owner, etc.). While it implies the difference from the sibling get_trademark_by_serial by specifying 'registration number', it does not explicitly differentiate. The purpose is clear but sibling distinction is only implied.

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

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

Description mentions the prerequisite of requiring a USPTO API key, which aids usage. However, it does not provide guidance on when to use this tool versus alternatives like get_trademark_by_serial or get_trademark_documents. No explicit when-not-to-use or exclusion criteria.

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 value by specifying the exact output fields and the authentication requirement (API key), which is beyond what annotations provide.

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

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

Two efficient sentences. The first sentence states the action and outputs; the second provides a critical prerequisite. No unnecessary words, 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 tool's straightforward nature, the presence of an output schema (so no need to detail return values), and comprehensive annotations, the description covers all essential aspects: purpose, inputs, outputs, and authentication.

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 parameter descriptions. The description reinforces the role of 'serial_number' and adds context about the API key being free and where to register, which is a slight enhancement over 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 'Look up a US trademark by serial number' and lists the specific data returned (status, owner, dates, goods/services, classification). It distinguishes itself from siblings like 'get_trademark_by_registration' by focusing on serial number 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 provides context by mentioning the required API key and where to get it. While it does not explicitly contrast with sibling tools, the purpose and input parameter (serial_number vs. registration number) imply when to use this tool.

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

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

Annotations already indicate read-only, idempotent, non-destructive behaviors. The description adds critical behavioral context: the requirement for a USPTO API key and the specific nature of the data retrieved (prosecution history), which is not covered by annotations alone.

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

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

The description is just two sentences with no wasted words. It immediately conveys the tool's purpose and a key requirement, making it easy to scan.

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 annotations, the description provides sufficient context for a trademark prosecution history retrieval tool. It could mention that the serial number must be in a specific format or refer to output structure, but the output schema likely covers that.

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 both parameters. The description echoes these (serial_number, api_key) but adds no new semantic detail beyond what the schema provides, so a baseline score of 3 is appropriate.

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

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

The description clearly states the tool retrieves prosecution history for a trademark by serial number, specifying the content (office actions, responses) and the identifier. This distinctly differentiates it from sibling tools like get_trademark_by_serial or get_trademark_by_registration.

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

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

The description mentions the prerequisite of a USPTO API key but provides no guidance on when to use this tool versus alternatives like get_trademark_by_serial or get_trademark_by_registration. The context is implied but not explicit.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds behavioral context by listing the returned fields and the ability to include inactive subscriptions via the parameter. 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 extremely concise with two sentences that efficiently communicate purpose, return fields, and 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 simple tool with one optional parameter, no output schema, and strong annotations, the description covers purpose, field details, usage guidance, and parameter behavior completely.

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

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

Schema coverage is 100% with a clear description for the single parameter. The tool description does not add further semantics beyond what the schema provides, so 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 lists the caller's active subscriptions and specifies the returned fields. It also distinguishes itself from siblings like 'subscribe' and 'unsubscribe' by focusing on listing existing subscriptions.

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

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

The description provides explicit when-to-use guidance: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' It lacks explicit when-not-to-use or 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 discloses rate limit (5 per identifier per day), that it's free and doesn't count against quota, and that team reads digests daily affecting roadmap. These details go beyond annotations (which only show non-read-only and non-destructive). 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?

Four sentences, each serving a clear purpose: first states the overall function, second lists use cases, third gives warning, fourth adds behavioral details. Front-loaded with purpose, no unnecessary words.

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

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

Given no output schema, the description focuses on input and behavior, which is sufficient. It covers complex aspects like nested context object, rate limiting, and usage rules. The tool's purpose is straightforward, and all critical information is 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?

Schema coverage is 100%, so the schema thoroughly documents all parameters. The description adds value by explaining the enum values more contextually and warning against including user prompts. However, the schema already provides detailed enum descriptions, so extra value is moderate.

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 allows reporting bugs, missing features, data gaps, or praise. It uses specific verbs like 'tell', 'broken', 'missing', 'needs to exist'. It is unique among sibling tools as no other feedback tool exists, ensuring no confusion.

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 enumerates when to use the tool for bug, feature, data_gap, praise, and other. Also specifies what not to do (don't paste user prompt) and mentions rate limit. This provides clear direction and distinguishes usage scenarios.

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

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

Adds beyond annotations: data source (CF analytics-engine), no PII, caching window (5min-1h). No contradiction.

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

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

Three tight sentences: purpose, use cases, transparency. No wasted words.

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

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

For a simple tool with rich annotations and schema, description covers all needed context: what, why, and behavioral traits.

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% with enum and description. Description adds little beyond 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?

Clearly states the verb 'returns' and resource 'top tools, top packs, call volume' over a window. Distinguishes from sibling tools like ask_pipeworx.

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

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

Explicitly lists three use cases (discovering hot data, confirming canonical tool, alignment). Does not specify when not to use, 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?

Exhaustive disclosure of behavioral traits: walks child markets, does Jaccard similarity checks, partition filter, fill check against live CLOB depth. Explains edge cases like skipped_low_similarity, placeholder dropping, and realizable_edge_pp ≤ 0. No contradiction with annotations (readOnly, openWorld, idempotent, non-destructive).

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

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

Well-structured with clear mode separation and front-loaded requirement. However, the description is lengthy and could be more concise, e.g., by grouping partition check details. Still, complexity justifies 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?

Comprehensive coverage given complexity and lack of output schema. Describes input formats, processing steps, output structure (opportunities[], partition_check), and fallback scenarios. Mentions sibling tool for custom sizing. No missing critical information for invocation.

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

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

Schema coverage is 100% with descriptions for both `event` and `topic`. Description enriches meaning substantially: explains mode differences, provides examples, notes that full URLs are accepted, and details how each parameter affects behavior. Adds value beyond schema.

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

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

Description clearly states the tool finds arbitrage opportunities via monotonicity violations and partition-sum checks. It distinguishes between event (single-event) and topic (cross-event) modes, and implicitly differentiates from sibling polymarket tools by focusing on arbitrage detection rather than just risk or edges.

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

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

Explicitly requires one of `event` or `topic` and explains failure without args. Provides detailed guidance on when to use each mode (event for specific market, topic for cross-event scanning). Mentions alternative tool `polymarket_fill_risk` for custom sizing. Lacks explicit exclusions or conditions where this tool should not be used.

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 provides extensive behavioral context, including three model families, edge calculation details, tradeable-edge knobs, response structure with diagnostics, and caching behavior. This goes far beyond the annotations (readOnlyHint, etc.) and discloses limitations like Fed bet exclusion.

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 main purpose. It is structured with clear sections, and every sentence provides necessary information for understanding the tool's complex behavior. However, it 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?

Given the tool's complexity, the description covers all essential aspects: purpose, model families, output structure, parameter roles, edge calculation, filters, and diagnostics. No gaps remain, especially considering no output schema exists.

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

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

Schema coverage is 100%, and the description adds meaningful context beyond the schema descriptions, explaining the rationale for parameters like min_liquidity and max_spread_pp as tradeable-edge filters. This adds value despite the schema already being detailed.

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, and is built for 'what should I bet on today'. This specific verb+resource combination distinguishes it from siblings 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 indicates the tool is for discovering betting opportunities without paging through hundreds of markets. However, it lacks explicit guidance on when not to use this tool versus alternatives like polymarket_arbitrage or polymarket_kalshi_spread.

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 extensive behavioral details: response structure (tracked, expired, snapshot_dates), limits (60-day TTL, snapshot enablement, decay from daily closes), and parameter effects. 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 thorough but not overly verbose. It front-loads the core purpose, then details response structure and limits. Every sentence adds value, though slight trimming could improve conciseness.

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

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

Despite no output schema, the description fully explains return values (tracked, expired, snapshot_dates) with fields and meaning. It covers limits and parameter behavior, 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 descriptions cover both parameters adequately. The description adds context: days is lookback with defaults and clamp, window is snapshot family. It also explains how parameters affect the response, enriching 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 provides 'edge persistence and decay telemetry' from daily snapshots, answering 'how long has this edge existed and is it shrinking?' It specifies the resource (edges from polymarket_edges snapshots) and distinguishes from siblings like polymarket_edges which likely provides 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 explains when to use this tool for historical edge analysis versus current snapshots, contrasting fresh vs old edges. It doesn't explicitly mention alternatives but implies context. Limits and snapshot behavior are specified, aiding 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 declare readOnlyHint=true, idempotentHint=true, etc. The description adds behavioral context beyond annotations: it walks the ladder, returns a verdict (clean|degraded|cannot_fill), and mentions forced_directional_risk. It also describes the risk of partial fills. 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 well-structured with uppercase labels (SINGLE-MARKET, BASKET) and lists of return fields. It is front-loaded with core purpose but somewhat wordy. Loses one point for length but maintains good 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?

Given the tool's complexity (two modes, many outputs, no output schema), the description is very complete. It explains both modes, parameters, return fields, and usage guidance. It also covers risky scenarios like partial fills and thin books.

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%, baseline is 3. The description adds meaning: explains side in both modes, size_usd for buys/sells, and distinguishes market vs event. It provides defaults and clamp range, 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's purpose: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It distinguishes between single-market and basket modes and explains return fields. It differentiates from sibling tools like polymarket_arbitrage and polymarket_edges by noting when to use it before acting on those signals.

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

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

The description explicitly provides usage guidance: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It explains the risk of partial fills converting arbs into unhedged positions, and differentiates when to use single-market vs basket mode.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds significant context: response fields (prices, spreads), compatibility_warning conditions (non-equivalent bet shapes, semantically unrelated events), temporal_alignment, and counters for skipped comparisons. 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 well-structured with clear sections (TWO MODES, RESPONSE, SAFETY FIELDS) and front-loads the core purpose. However, it is somewhat verbose, with some sentences that could be tightened.

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 modes, safety fields) and lack of output schema, the description covers the response format, safety conditions, and edge cases well. It explains compatibility_warning and temporal misalignment thoroughly. Minor over-explanation but complete.

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

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

Schema coverage is 100% with descriptions for all parameters. The description adds meaning by explaining the topic parameter's valid values and how explicit parameters override topic-mapped ones. This adds context 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 computes cross-venue spread between Kalshi and Polymarket for the same resolving question. It distinguishes itself from siblings like polymarket_arbitrage and polymarket_edges by focusing on cross-venue comparison, not within-venue 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 explains two modes (topic shortcuts and explicit tickers) and provides guidance on when to use each. It warns that most pre-mapped topics return compatibility warnings, setting realistic expectations. However, it does not explicitly state when to avoid using this tool (e.g., when only one venue is needed).

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

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

Annotations already indicate readOnlyHint=true, destructiveHint=false, and idempotentHint=true. The description adds behavioral details such as scoping to identifier and the dual behavior (retrieve vs list) 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 concise, front-loaded with the core function, and uses a single paragraph with clear examples. Every sentence adds value.

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

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

Given only one optional parameter, no output schema, and comprehensive annotations, the description fully explains behavior, scoping, and relationships with sibling tools.

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

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

Schema describes the 'key' parameter fully (optional, omit to list). The description echoes this same information, adding no new parameter semantics beyond showing usage examples.

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

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

The description clearly states that the tool retrieves a stored value or lists all keys, specifically mentioning the association with 'remember' and 'forget' siblings, thus distinguishing it from other tools.

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

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

Provides explicit usage context: looking up previously stored context like tickers, addresses, or notes. Also mentions scoping and pairing with remember/forget for a complete workflow.

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

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

Annotations declare readOnlyHint true, but the description states 'mark_read:true' modifies read status, implying mutation. This contradiction undermines trust in the description's behavioral disclosure.

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

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

The description is efficient, using three sentences to cover purpose, return data, and usage notes. It is front-loaded but could be more terse without losing key details.

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

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

Given 5 optional parameters and no output schema, the description covers return fields, filtering, mark_read behavior, and polling. It lacks mention of 'unread_only' and error cases, but overall is sufficiently complete for typical use.

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

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

100% schema coverage provides baseline clarity. The description adds example filter values and 'mark_read' behavior but does not address the 'unread_only' parameter, leaving some gaps.

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

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

The description clearly states the verb 'Pull' and resource 'fired events from your subscription feed', listing specific return fields (source, citation_uri, raw payload) and options. It distinguishes from sibling tools like 'list_subscriptions' by focusing on alerts and their 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 provides clear context on usage: filtering options, polling, and an alternative REST endpoint. However, it does not explicitly compare with sibling tools or state when not to use this tool.

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

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

Annotations already declare safe, read-only, idempotent behavior. Description adds further detail: fans out to multiple sources with fallback, mentions PatentsView sunset and soft-failure, explains ISO/relative date support.

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

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

Concise yet comprehensive—each sentence adds value. Front-loaded with example queries, then explains inputs, sources, and fallback. No unnecessary filler.

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

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

Despite no output schema, description mentions return structure (changes[] grouped by source, total_changes, citation URIs). Covers all complexity: sources, fallback, date formats, sibling comparison.

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 meaning: examples of relative shorthand ("7d", "30d", "3m", "1y"), explains value accepts ticker or CIK, and clarifies type only supports 'company'.

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

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

The description clearly states the tool fetches a change feed for a company across SEC, GDELT/GNews, and USPTO. It provides multiple example queries ("What's new with X") and distinguishes itself from sibling tool 'entity_profile' by specifying 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 tells when to use (change feed for recent period) and when not to (static profile → entity_profile). Also explains fallback behavior (GDELT→GNews) and date format handling.

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. Description adds scoping (by identifier) and persistence differences (authenticated vs anonymous, 24-hour TTL), which are valuable 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?

Efficient 5-sentence description that front-loads purpose, wastes no words, and is well-structured with usage guidance and pairing 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 no output schema, description adequately covers all relevant context: when to use, what to store, scope, persistence, and companion tools. Complete for this simple store 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 key and value with basic descriptions. Description adds examples for key naming conventions (e.g., 'subject_property') and value type ('any text'), enhancing semantic clarity beyond the schema.

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

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

Description clearly states verb ('Save data') and resource ('key-value pair') for reuse later. Distinguishes from siblings recall and forget by framing as the write operation.

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 defines when to use: 'when you discover something worth carrying forward' with concrete examples. Also mentions pairing with recall and forget, giving clear context vs alternatives.

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

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

Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds valuable context: it cascades through multiple internal lookup endpoints (replacing 2-3 manual lookups) and specifies exact return details per entity type (including citation URIs). No contradictions with annotations.

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

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

The description is front-loaded with usage examples and purpose, then organizes supported types in a structured manner. Every sentence adds value, though it could be slightly more concise without losing clarity. Still efficient 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 specifies return values for both entity types, including citation URIs. The internal cascading behavior is explained, and coverage for parameters is complete. The tool's role in the ecosystem (replace manual lookups) is clear, making it complete for an agent.

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

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

Schema has 100% coverage, but the description enriches both parameters significantly. For 'type', it explains accepted values with examples. For 'value', it details accepted input formats (ticker, CIK, name for company; brand/generic for drug) and what is returned, adding meaning beyond the schema's succinct 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 is clear and specific: it resolves a user-spoken name to a canonical/official identifier. It provides concrete examples (ticker, CIK, RxCUI) and explicitly states to use it first when a name needs an ID, distinguishing it from sibling tools like entity_profile or compare_entities.

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

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

The description explicitly says 'Use FIRST whenever you have a name but need an ID,' providing clear usage context. It doesn't list specific alternatives but implies other tools require the IDs this tool resolves, which is sufficient for an agent.

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 non-destructive. The description adds that each entity is probed with ai_visibility_check and the first entity is treated as the 'subject' for narrative. This provides methodology 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?

Three sentences: first states purpose and mechanism, second gives example use case, third summarizes output. Every sentence is informative 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?

Given rich annotations (safety, idempotency) and full schema coverage, the description fully explains the tool's workflow, output (ranked list with score, confidence, signal density), and competitive audit context. 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?

Schema coverage is 100%, baseline 3. The description adds significant meaning: explaining that entities are compared, first is subject, that models can be ommitted, and that context disambiguates names. This compensates 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 verb 'Compare' and the resource 'AI visibility across multiple entities side-by-side'. It explicitly distinguishes from sibling 'ai_visibility_check' by emphasizing multi-entity comparison and ranking.

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

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

The description provides a concrete use case ('competitive AI-marketing audits') and hints at alternatives by mentioning probing with ai_visibility_check. However, it does not explicitly say when not to use this tool.

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

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

Beyond annotations (readOnlyHint, idempotentHint), description adds details about partial failures, bundlephobia timing (5-30s), and graceful degradation with sources_failed listing timeouts. No contradictions with annotations.

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

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

Three sentences, front-loaded with purpose. Each sentence is informative, though could be slightly more concise. No filler or redundancy.

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

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

Despite no output schema, description fully explains return content (summary block, per-advisory detail, links, alternative versions) and covers behavioral edge cases (partial failures, timeouts). Adequate 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%, so baseline 3. Description adds extra context: scoped packages like '@types/node' are accepted for 'package', and 'version' defaults to latest when omitted. This adds meaningful value beyond schema.

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

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

Description explicitly states tool as a composite check for adding npm packages, fanning out across deps.dev and bundlephobia. It clearly identifies the resource (npm package) and distinguishes from siblings by noting that other ecosystems are covered by deps.dev:version directly.

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

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

Provides explicit guidance: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me".' Also specifies exclusion: 'NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly.'

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

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

Annotations already provide safety hints (readOnly, idempotent). Description adds technical details: BGE-base-en embeddings, cosine similarity, 500-char windows, 200K char limit, truncation flagging, and offset returns. 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?

Concise yet comprehensive: first sentence states core purpose, then usage guidance, then technical details. Every sentence adds value; no fluff.

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

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

Despite no output schema, description explains return values (passages with offsets and scores) and addresses limitations (char cap, truncation). Complete for a tool with 3 params and no output schema.

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

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

Schema covers all 3 parameters (100% coverage). Description adds examples for 'query' (e.g., 'supply-chain risk') and explains 'text' cap and truncation behavior, enhancing 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?

Clearly states 'semantic search INSIDE a fetched record' with specific verb (search) and resource (record). Distinguishes from sibling tools like 'ask_pipeworx_grounded' by noting pairing.

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 when the record is too big to cram into the prompt' and mentions pairing with 'ask_pipeworx_grounded' as an alternative workflow.

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: requires OAuth account, SMS cap (10/day), webhook auto-disable after 10 failures, and one-time secret return. However, it does not clarify idempotency behavior (annotation says idempotent, but description doesn't mention whether repeated calls create duplicates).

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 main action and returns. Structure is logical: action, requirements, types, delivery. Slightly long but justified by the number of types and delivery options. 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?

No output schema, description states 'Returns the new subscription id' and for webhook mentions the secret. Lacks full response object details such as whether the subscription object is returned or only the id. Could be more 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% (all parameters described), and the description significantly enriches understanding with concrete examples for each type and delivery channel, including nested object structure for params and delivery.

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

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

The description clearly states the tool creates a proactive monitoring subscription and returns a subscription id. It distinguishes itself from sibling tools like 'unsubscribe' and 'list_subscriptions' by specifying the creation action and output.

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

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

It provides context on when to use (proactive monitoring) and requirements (Pipeworx OAuth account). It does not explicitly state when not to use or point to alternatives, but the detail on types and delivery channels helps infer 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?

Beyond annotations (readOnlyHint, openWorldHint, idempotentHint), the description adds behavioral context: it returns example questions, is the entry point, and can be focused by topic. 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 well-structured, front-loading common queries and then explaining output and usage. It is slightly long but 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?

For a tool with one optional parameter and no output schema, the description fully covers purpose, usage, output format, and guidance on when to use it. It is contextually 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 the baseline is 3. The description adds examples ('finance', 'pharma', 'betting') but doesn't add new semantic meaning beyond the schema's enum-like listing.

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

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

The description clearly identifies the tool as an onboarding entry point that returns category-bucketed example questions with exact tool+argument shapes. It distinguishes from siblings by explicitly recommending use when the agent doesn't yet know what Pipeworx can do, and contrasts with meta-tools.

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

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

The description explains when to use the tool (first interaction, getting started) and how to use it (with no arguments for full spread, or topic parameter to focus). It doesn't explicitly exclude other tools but provides clear context for its intended role.

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

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

The description discloses key behavioral traits beyond annotations: ownership enforcement (only cancel own subscriptions), soft deletion (deactivated not deleted), and side effect of preserving historical events via 'recent_alerts'. Annotations indicate idempotent and non-destructive, which align with the soft delete 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 two sentences long, front-loading the core action and immediately adding constraints and side effects. Every sentence adds value without redundancy.

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

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

For a simple tool with one parameter and no output schema, the description covers purpose, constraints, and side effects. The idempotent hint from annotations complements the description well.

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 provides 100% coverage for the 'id' parameter with a clear description. The description does not add additional semantic meaning beyond what is in the schema, meeting the baseline for full 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 uses the specific verb 'Cancel' and refers to 'subscription by id', clearly indicating the action and resource. It distinguishes from sibling tools like 'subscribe' and 'recent_alerts' by mentioning ownership enforcement and soft deletion with historical availability.

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 intended usage is clear from 'Cancel a subscription by id', but it does not explicitly state when not to use or provide alternative tools beyond mentioning 'recent_alerts' for historical data. The ownership enforcement implies a precondition.

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

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

Annotations already indicate safe, read-only, and idempotent behavior. The description adds valuable context: return format (verdict, structured form, citation, percent delta), data sources (SEC EDGAR + XBRL), and efficiency gains. 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 well-structured, front-loaded with examples and purpose, and every sentence contributes value. It is concise yet comprehensive for the tool's complexity.

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

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

Given the single parameter, annotations, and lack of output schema, the description covers use case, domain, return values, and efficiency. Minor gaps: no mention of error handling or behavior for out-of-domain claims, but overall 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% and already describes the 'claim' parameter with examples. The description repeats similar examples but does not add new semantic meaning beyond what the schema provides, so baseline score of 3 is appropriate.

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

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

The description clearly states the tool validates natural-language factual claims against authoritative sources, with specific examples and domain (company-financial). However, it does not explicitly differentiate from sibling tools like ask_pipeworx_grounded, though it implies uniqueness by claiming to replace multiple sequential calls.

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

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

The description explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct' and specifies the supported domain. It lacks explicit when-not-to-use or alternative tools, but the guidance is clear and contextually appropriate.

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