Openfigi

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false. The description adds value by explaining the scoring mechanism, model selection (default Workers AI, optional Anthropic with BYO key), and return format (per-model fields). No contradictions.

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

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

Three sentences with clear front-loading of main functionality. No fluff, every sentence provides useful info. Efficiently structured for quick comprehension.

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

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

For a tool with 4 parameters, no output schema, and no nested objects, the description is complete: it explains purpose, usage, parameters, return structure, and cost implications. No gaps left for an AI agent.

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

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

Schema coverage is 100%. The description adds context beyond the schema: explains default model, that _apiKey is required for Anthropic and passed directly, and that 'context' helps disambiguate. This enriches parameter meaning.

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

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

The description clearly states it probes LLMs for entity knowledge and scores visibility (0-100) per model. It specifies the resource (LLMs, entity), verb (probe/score), and return structure, distinguishing it from related sibling tools like 'scan_competitor_ai_presence' by focusing on general entity visibility rather than competitors only.

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

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

Provides explicit use cases ('AI-marketing audits, pre-launch brand checks, competitive monitoring') and mentions default vs. paid model options. Does not explicitly state when not to use or name alternatives, but the context is clear enough for an AI agent to infer appropriate 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?

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds behavioral context beyond annotations, such as routing to 4,819 tools, returning structured answers with citation URIs, and being a fast single call. It does not contradict annotations.

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

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

The description is well-structured with clear sections: preference guidance, purpose explanation, examples, and step-up instructions. While it is somewhat verbose, every sentence adds value and is front-loaded with the key message.

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 its capability, usage scenarios, and return format (structured answer with citations). While it lacks details on error handling or edge cases, it provides sufficient context for an AI agent to select and invoke the tool correctly.

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

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

Schema coverage is 100% with all parameters documented as aliases for 'question'. The description enhances parameter semantics by providing extensive examples of valid questions and the types of data queried, which helps the agent formulate appropriate parameter values.

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

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

The description clearly states the tool's purpose: it routes questions to a vast array of sources and returns structured answers with citations. It distinguishes itself from siblings by explicitly stating 'PREFER OVER WEB SEARCH' and providing guidance on when to use alternatives like ask_pipeworx_grounded and deep_research.

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

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

The description provides explicit when-to-use and when-not-to-use guidance. It specifies that the tool should be the default for factual questions and lists scenarios where alternative tools are more appropriate, such as hallucination-resistant answers or broad multi-part questions.

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

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

Annotations already indicate safe read-only idempotent behavior. The description adds detailed behavioral context: it extracts only from tool result, lists possible refusal reasons (not_in_source, no_tool_match, etc.), and notes the additional LLM call cost, providing transparency 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 front-loaded with the key purpose and outcome, then provides detailed behavior and use cases. Every sentence contributes value. Slightly verbose but still efficient for the complexity.

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

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

Fully compensates for missing output schema by describing the return structure (answer, evidence, confidence, etc.) and refusal reasons. Provides cost trade-off and sibling differentiation. All necessary context for an agent to invoke correctly is present.

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

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

Schema coverage is 100% with all parameters aliases for 'question,' each described as such. The description adds only 'Your question in natural language,' which is redundant with the schema. Baseline 3 given high coverage; no additional semantic value.

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

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

The description clearly states it is a 'hallucination-resistant answer mode for high-stakes reads,' and contrasts with ask_pipeworx by specifying it extracts answers only from tool results and returns evidence. It distinguishes from siblings by naming the exact use case.

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

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

Explicitly advises to use for high-stakes scenarios where answers will be quoted or acted upon (financial, legal, medical), and to prefer ask_pipeworx for casual lookups due to the extra cost. This provides clear when-to-use and when-not-to-use guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, destructiveHint=false. Description adds extensive behavioral details: resolver confidence levels, parent event extraction, news fallback fields, safety short-circuits, wide spread handling, and cancellation rule parsing. Contradiction is absent.

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

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

The description is lengthy but densely informative; every sentence adds value. Front-loaded with core purpose. Could benefit from more structural formatting (e.g., bullet lists) to improve scanability, but remains 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 no output schema, the description compensates by detailing response shapes (result.market, result.analysis, result.evidence), resolver contract, parent_event, news fallback, safety, and cancellation rules. Covers all essential aspects for an AI agent to use the tool correctly.

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

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

Schema description coverage is 100% with each parameter described. The description enriches meaning with examples of market input formats, depth enum behavior ('quick' vs 'thorough'), and include_raw implications. Fan-out examples illustrate depth behavior contextually.

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

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

The description clearly states it researches a single Polymarket bet by pulling Pipeworx data. It distinguishes from siblings like polymarket_arbitrage and polymarket_edges by specifying use cases like 'should I bet on X', making purpose and differentiation explicit.

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

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

Provides explicit use cases: 'should I bet on X', 'what does the data say about Y', 'is there edge in Z'. Does not explicitly exclude alternative tools, but context and examples imply appropriate usage. Safety notes like blocking on low confidence add behavioral context.

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

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

Annotations already declare read-only, open-world, idempotent. Description adds specific data sources (SEC EDGAR/XBRL, FAERS), metrics, sorting by primary metric, and citation URIs. No contradiction.

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

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

Packed with information but slightly lengthy. Front-loaded with examples, uses compact structure. Every sentence earns its place but could be trimmed slightly.

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

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

Covers both entity types fully, mentions edge cases (off-calendar fiscal years), and describes return format (paired data + URIs). No output schema, but description 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 has 100% coverage, but description adds meaning: explains values for company vs drug, provides examples, and clarifies min/max items.

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?

Starts with example user queries, clearly states side-by-side comparison of 2-5 companies or drugs in one parallel call. Distinguishes from sequential lookups and siblings.

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 sequential single-pack lookups' and provides when-to-use examples. Implicitly excludes single entity lookups.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds crucial context: returns 'findings packet with verbatim evidence + confidence + source + fetched_at + stable pipeworx:// citation', 'explicit gaps[]', 'never invented'. It also mentions parallelism, expected time (15-60s), and that it is not open-web search. No contradiction.

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

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

The description is somewhat long but highly structured: critical info (account, alternatives) is front-loaded. Each sentence provides unique value, though a small amount of repetition could be trimmed. Overall efficient for the complexity covered.

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 prerequisites, return format, limitations (breaking news), performance expectations, and distinguishes from siblings. No output schema exists, but the description adequately explains what the tool returns and its structure.

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

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

Schema coverage is 100%, but the description adds significant value: for 'depth' it explains what each enum value means ('quick=3, standard=5 (default), thorough=8') and that 'thorough' needs paid plan. For 'question' it clarifies that 'Broad/multi-part is fine — decomposition is the point.' This goes well beyond the schema.

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

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

The description clearly states it conducts 'grounded multi-source research' across '1259 STRUCTURED data sources' using '4,819 tools IN PARALLEL'. It distinguishes from siblings like ask_pipeworx and explicitly contrasts with open-web search.

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

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

Prerequisites (account via GitHub, paid plan for 'thorough') are stated upfront. When to use is explicitly given: 'For a single lookup use ask_pipeworx', 'For BREAKING or colloquial CURRENT-NEWS topics, prefer ask_pipeworx'. Also provides fallback if not signed in.

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 idempotency and non-destructiveness. The description adds specific behavioral details: 'Returns the top-N most relevant tools with names, descriptions, and full input schemas (with curated examples) — each result is ready to call directly.' No contradictions.

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

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

The description is concise and front-loaded. First sentence states the purpose, followed by usage guidance, then return format, and finally when to call. 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?

The description covers purpose, usage, and return format adequately. It explains what is returned and that no second schema lookup is needed. However, it does not mention how relevance scoring or sorting works, which is a minor gap given no output schema.

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

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

Schema coverage is 100%, so baseline is 3. The description does not add significant parameter semantics beyond what the schema provides; it only contextualizes the query parameter with domain examples, but the schema already covers descriptions and aliases.

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 finds tools by describing data or task, and provides explicit usage context ('Call this FIRST'). It distinguishes itself from sibling search tools by focusing on tool discovery rather than data search.

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

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

The description gives explicit guidance: '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.' It provides clear context for when to invoke 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 readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds value beyond this: it notes the parallel call behavior, references patents API sunsetting (May 2025, soft-fails), and mentions fallback mechanisms (GDELT→GNews). No contradiction with annotations.

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

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

The description is front-loaded with examples and a clear purpose statement. It is somewhat long but every sentence adds value, covering input format, output components, and limitations. Could be slightly more concise but structure is logical.

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

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

Given no output schema, the description thoroughly explains return values (CIK, filings, fundamentals, patents, news, LEI) with specific details (e.g., 'up to 5 filings', 'LATEST 10-K Revenues + NetIncomeLoss + Cash'). It notes limitations (US only, patents sunset, names unsupported) and mentions the parallel nature. Complete for a holistic profile tool.

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

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

Schema coverage is 100%, baseline 3. The description adds explicit examples for the 'value' parameter ('AAPL', '0000320193'), clarifies that names are not supported, and directs to resolve_entity for name resolution. This adds meaningful guidance 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 explicitly states 'full cross-source profile of a US public company in ONE parallel call' with concrete examples like 'tell me about X' and 'company profile for Microsoft'. It clearly distinguishes the tool from chaining single-pack lookups by stating 'ALWAYS PREFER over chaining...'.

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

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

The description provides explicit guidance: 'ALWAYS PREFER over chaining... when the user asks for a holistic view'. It also states when not to use (names not supported, use resolve_entity first) and mentions alternative tool (resolve_entity).

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, etc. The description adds context about return fields and optional parameters, but does not disclose any additional behavioral traits beyond what the annotations provide.

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

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

The description is a single, well-structured sentence that front-loads the action 'Filter' and efficiently conveys the purpose, parameters, and return value without extraneous words.

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

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

Given the tool's complexity (4 params, 0% schema coverage) and the presence of an output schema, the description covers the basics but lacks full parameter documentation. It mentions all parameters and return fields, but could better explain idType values and constraints.

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

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

With 0% schema description coverage, the description compensates by providing examples (e.g., idType='TICKER') and mentioning optional params. However, it does not enumerate possible idType values or specify parameter constraints, leaving some ambiguity.

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 specifies filtering OpenFIGI instruments by identifier type and value, which is a specific verb+resource. It provides a concrete example (TICKER) and mentions return fields (FIGIs, descriptions, market sector). However, it does not explicitly differentiate from sibling tools like 'search' or 'resolve_entity', which might have overlapping functionality.

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

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

The description implies usage for filtering by identifier with optional exchange code or currency narrowing, but it does not provide explicit guidance on when to use this tool versus alternatives, nor does it mention when not to use it.

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

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

Annotations already provide destructiveHint=true and idempotentHint=true. Description adds that the memory must be 'previously stored', implying the key must exist, which is extra context beyond annotations.

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

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

Two concise sentences, front-loaded with the core action, no filler. 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?

All necessary context is present: action, usage guidance, and pairing with sibling tools. For a simple tool with 1 param and good annotations, this is complete.

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

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

Schema coverage is 100% with a single parameter 'key' described as 'Memory key to delete'. The description merely references 'by key' without adding new meaning beyond the schema.

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

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

Clearly states 'Delete a previously stored memory by key' – specific verb (delete) and resource (memory), distinguishing it from siblings like 'remember' and 'recall'.

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

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

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

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, openWorldHint=true, and destructiveHint=false, indicating safe, read-only, idempotent behavior. The description adds that it fetches the page, extracts title/description/key links, and emits standard format, but does not disclose important details like error handling for unreachable URLs or rate limits. The annotations cover the core safety profile, so the description's additional context is adequate but not extensive.

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

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

The description is three sentences long, front-loaded with the core purpose, followed by the process and use cases. Every sentence contributes essential information with no redundancy or 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?

For a tool with two parameters, no output schema, and straightforward functionality, the description covers the main purpose, process, and use cases. Minor gaps exist, such as specifics on error handling or the exact output format, but the mention of 'standard llms.txt markdown format' and 'single text blob' provides sufficient context for an AI agent to understand the outcome.

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%; both 'url' and 'max_links' have clear descriptions in the schema. The tool description mentions the URL and default max links but does not add new meaning beyond what the schema already provides. Thus, the description adds marginal value for parameters.

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

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

The description clearly states that the tool generates a production-ready llms.txt file for any URL, specifying the verb 'Generate' and the resource 'llms.txt'. It distinguishes itself from sibling tools like 'ai_visibility_check' and 'scan_competitor_ai_presence' by focusing specifically on llms.txt generation.

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

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

The description lists specific use cases: getting a client's site indexed by AI, drafting llms.txt for a project, or auditing a competitor's site. This provides clear context for when to use the tool, but it does not explicitly state when not to use it or compare it to sibling alternatives.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds that it returns specific fields and includes an optional parameter, but does not add significant behavioral context 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 sentences, no wasted words. Purpose is front-loaded, and the description is efficient and easy to parse.

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

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

No output schema exists, but the description lists returned fields. The tool is simple with one optional parameter, and the description covers the important aspects for an agent to use it effectively.

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 description. The tool description does not add extra meaning to the parameter beyond the schema, so baseline score of 3 is appropriate.

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

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

The description states 'List the caller's active subscriptions' and lists returned fields. It clearly identifies the resource and action, distinguishing it from siblings like 'subscribe' and 'unsubscribe'.

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

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

Provides explicit use cases: 'review what you're monitoring before adding more or to find an id to cancel'. This helps the agent decide when to use it, though it does not explicitly state when not to use it.

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

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

Annotations already declare safe, idempotent behavior. Description adds no extra behavioral context (e.g., partial success, error handling, or rate limits), but does not contradict annotations.

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

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

Single well-structured sentence that is front-loaded and efficient, with no extraneous text.

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

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

Tool has output schema and annotations, but description does not elaborate on return values or edge cases. Adequate for a simple mapping tool, but could mention output format.

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

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

Schema coverage is 100%, and description merely restates the schema's structure. No additional semantic meaning 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?

Description uses specific verb 'Map' and resource 'instrument-id queries → FIGIs', clearly distinguishing it from sibling tools like search or filter.

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

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

No guidance on when to use this tool versus alternatives such as search, resolve_entity, or filter. The description lacks context for optimal invocation.

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

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

Annotations indicate mutability but not destructiveness. The description adds valuable behavioral context: rate limit (5/identifier/day), free usage, and that team reads digests daily. 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?

Every sentence serves a purpose, starting with the core action, then use cases, then behavioral notes. No redundant information; highly efficient.

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

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

Given the simplicity of the tool (3 parameters, no output schema), the description covers all necessary aspects: purpose, usage, parameter guidance, and behavioral traits. It is 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 coverage is 100%, so baseline is 3. The description adds extra meaning by advising against pasting end-user prompts and emphasizing to describe issues in terms of Pipeworx tools/packs, which aids correct usage.

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

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

The description clearly states the tool's purpose: sending feedback about broken, missing, or needed features. It lists specific types (bug, feature, data_gap, praise) and distinguishes itself from sibling tools by being the feedback channel.

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

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

Explicitly describes when to use each feedback type (bug, feature/data_gap, praise) and what not to do (paste end-user prompt). Also covers rate limits, quota, and how the feedback is used, providing comprehensive guidance.

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

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

Annotations declare readOnly, idempotent, non-destructive. Description adds that data is self-aggregating from CF analytics-engine, contains no PII, and is cached 5min-1h depending on window. This fully discloses behavior 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?

No unnecessary words: every sentence adds value. The main purpose is front-loaded, and the structure is compact yet complete.

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 optional param and no output schema, the description covers return values, data source, privacy, caching, and use cases. Leaves no key gaps.

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

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

Schema coverage is 100% and already provides a description for the 'window' parameter. The tool description adds only a caching note, which is more behavioral than semantic. 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 returns trending tools and packs based on other AI agents' calls. The verb 'returns' and resource 'Pipeworx trending' are specific, and the scope is well-defined.

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

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

Three explicit use cases are provided (discovering hot data sources, confirming canonical tools, aligning use cases). No alternatives or when-not-to-use are mentioned, but the usage scenarios are clear.

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

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

Annotations indicate read-only, open-world, idempotent, non-destructive behavior. The description adds substantial context beyond annotations: semantic anchor with Jaccard similarity, partition filter with placeholder fraction, fill check against live order book depth, and response structure. No contradictions detected.

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 (trending scan, event mode, topic mode, fill check) and front-loaded with purpose. While somewhat verbose, every sentence adds necessary detail for a complex tool, and the organization aids readability.

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

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

The description covers all aspects: two operation modes, parameter usage, response format (opportunities array, partition_check object), fill check with trade/no-trade conditions, and cross-event semantics. It references a sibling tool for custom sizing, and despite no output schema, the description sufficiently explains return values.

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

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

Schema coverage is 100% (both parameters have descriptions). The description adds significant value beyond the schema: explains that event mode accepts full URLs, topic mode searches related events, and provides usage examples. This extra context raises the score above the baseline of 3.

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

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

The description clearly states the tool finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes two modes (event and topic) and explains the output structure, making the purpose specific and 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 provides explicit guidance on when to use each parameter (no args for trending scan, event for single-market, topic for cross-event) and includes a fill check advising when not to trade. It does not explicitly compare to sibling tools, but the within-tool guidance is clear and actionable.

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, destructiveHint=false, indicating safe, read-only, idempotent operation. The description adds substantial behavioral context: caching (1h KV), output structure (by_segment, fed_candidates, _diagnostics), edge calculation details, and filtering logic (placeholder-slug filter, Fed bets exclusion). 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 verbose (multiple paragraphs) and includes detailed internal model explanations (e.g., GDELT, lognormal barrier, partition_overround). While well-structured with clear sections, it lacks conciseness—many implementation details could be shortened or moved to external docs. An AI agent may find it dense.

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

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

With no output schema, the description fully compensates by detailing the response format (by_segment with model_driven, structural_arbitrage, concentrated_longshot; fed_candidates; _diagnostics). It explains edge fields, Kelly fractions, and filter knobs. For a complex 9-parameter tool with zero required params, the description covers usage, behavior, and output comprehensively.

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

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

Schema coverage is 100%, so the schema already documents all 9 parameters. The tool description adds extra context for some parameters (e.g., slippage_pp note about Polymarket fees, min_liquidity as 'Tradeable-edge filter'), but this is marginal. The description reinforces parameter values but doesn't fundamentally expand meaning beyond schema.

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

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

The description clearly states 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It specifies the resource (Polymarket markets) and the action (scan and return opportunities). The title 'Polymarket Edges' and the mention of 'what should I bet on today' further clarify. It distinguishes from siblings like polymarket_arbitrage and polymarket_kalshi_spread by focusing on Pipeworx disagreement.

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

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

The description positions the tool for daily edge discovery ('what should I bet on today') but does not explicitly compare with sibling tools like polymarket_arbitrage or polymarket_kalshi_spread. It explains the model families (model_driven, structural_arbitrage, concentrated_longshot) which imply use cases, but lacks explicit when-not-to-use or alternatives.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds significant behavioral context: data comes from daily snapshots written on cache-miss, history depth bounded by 60-day TTL, decay computed from daily closes (not intraday), and response structure including tracked, expired, and snapshot_dates arrays. 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 well-structured: purpose first, then args, then response format, then limits. It is front-loaded with the core question. However, it is somewhat verbose, especially in the response section where it details fields in prose. Could be slightly shorter while retaining all information.

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

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

Given the tool has no output schema, the description fully explains the return structure (tracked[], expired[], snapshot_dates[]) and their fields (first_seen, trend, decay_pp_per_day, lifespan_days, etc.). It also covers limits (TTL, non-intraday) and data freshness. This is complete for an agent to understand and use the tool correctly.

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

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

Schema has 100% description coverage for both 'days' and 'window', but the description adds value: it explains that 'days' is a lookback clamped to 2-30 (default 14) and 'window' selects a snapshot family (default '1wk'). This goes beyond the schema's basic type/description by clarifying behavior and constraints.

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

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

The description clearly states it provides 'edge persistence and decay telemetry' and answers a specific question about edge age. It distinguishes this tool from raw edge retrieval (sibling polymarket_edges) and arbitrage (polymarket_arbitrage) by focusing on time-series behavior. The verb 'track' and resource 'edge persistence' are specific and 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 gives strong usage context by contrasting a fresh wide edge with a 3-week-old one, implying when to use this tool for historical edge analysis. It also explains limits (TTL, non-intraday), though it doesn't explicitly exclude cases or name alternative tools. The sibling list provides context for differentiation.

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

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

Annotations (readOnlyHint, idempotentHint, destructiveHint=false) are consistent with the description, which adds critical behavioral details: it is a read-only check, requires exactly one of market or event, and warns that partial basket fills convert an arb into an unhedged directional position. The description enhances understanding 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 thorough but somewhat lengthy. It is well-structured with capitalized section headers (REQUIRES, SINGLE-MARKET, BASKET) and front-loads the purpose. Every sentence is informative, though a slightly more condensed version might improve brevity without losing content.

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

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

Despite lacking an output schema, the description lists all return fields (e.g., top_of_book, vwap_fill_price, slippage_pp, verdict) and explains the meaning of each. It covers the forced_directional_risk and thin_legs, ensuring the agent fully understands what the tool returns. The tool's complexity is well-matched.

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?

Although schema coverage is 100%, the description provides essential context: explains the two modes requiring market or event, defines side values per mode, interprets size_usd differently for buys vs sells and single-market vs basket, and clarifies defaults. This adds significant 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 checks realizable vs theoretical edge against live order book depth. It distinguishes two modes (single-market and basket) and explicitly relates it to sibling tools polymarket_arbitrage and polymarket_edges, making the purpose specific and non-overlapping.

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

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

Explicit guidance: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. It explains why (theoretical overround not capturable on thin books, partial fills create directional risk), providing clear context for when and when not to use.

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

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

Description goes far beyond annotations (readOnlyHint, idempotentHint) by detailing safety fields (compatibility_warning, temporal_alignment, skipped_cross_type), explaining when spreads are invalid, and stating that the tool indicates non-equivalent bet shapes. 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?

Description is well-structured with sections (TWO MODES, RESPONSE, SAFETY FIELDS) and front-loaded with purpose. However, it is verbose (around 400 words) and could be trimmed slightly while retaining 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?

With no output schema, description compensates by explaining return values (leg-by-leg prices, spread field), safety fields, and temporal alignment. It covers all necessary aspects for a complex tool, making it 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 all parameters described. Description adds value by listing exact topic values and explaining override behavior for explicit tickers. While baseline is 3, the extra context and examples justify a 4.

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

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

Description clearly states purpose: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It distinguishes from sibling tools like polymarket_arbitrage by focusing on cross-venue comparison, and explains two primary modes (topic shortcuts and explicit tickers) with specific examples.

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 provides explicit guidance on when to use each mode (topic for shortcuts, explicit for custom pairs) and warns about compatibility issues ('most pre-mapped topics return compatibility_warning today'). It lacks explicit comparison to sibling tools like polymarket_arbitrage, but still gives clear context for usage.

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

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

Adds behavioral detail beyond annotations: listing all keys on omit, scoping to identifier. Consistent with readOnly and idempotent hints.

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

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

Three concise sentences with clear action, examples, and scope. 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?

For a simple retrieval tool with one optional parameter and no output schema, the description covers purpose, usage, behavior, and scope 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?

Describes the effect of omitting the key parameter (list all keys), adding value over the schema description. Schema coverage is 100% but description enriches semantics.

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

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

Description explicitly states the tool retrieves values saved via remember or lists all keys when key is omitted. Clearly distinguishes from sibling tools remember and forget.

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

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

Explicitly says use to look up stored context like ticker or notes, without re-deriving. Mentions scoping and pairing with remember/forget.

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

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

Goes beyond annotations (readOnlyHint, idempotentHint) by explaining that events are from a persisted feed, mark_read affects subsequent calls, and the tool returns raw event payloads. 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?

Three sentences, front-loaded with purpose, then details, then additional behavior and alternatives. No fluff, 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 exists, but description details return fields (source, citation_uri, raw payload). Covers all parameters, provides usage context (polling), and offers an alternative access method. Complete for a non-destructive, read-only tool.

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

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

Adds significant meaning beyond the schema: explains mark_read as flagging events read so next call shows newer ones, gives example filter values (e.g., sec_8k), and clarifies return fields. Schema coverage is 100%, but description still enhances understanding.

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

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

The description clearly states the tool pulls fired events from a subscription feed and returns recent alerts with specific fields (source, citation_uri, raw payload). It distinguishes from sibling tools like list_subscriptions by focusing on alert events.

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 guidance on filtering by type and/or since, using mark_read, and mentions polling suitability. Suggests an alternative method (GET endpoint) for scripts/dashboards, but does not explicitly contrast with sibling tools like subscribe/unsubscribe.

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, destructiveHint false, so safety and non-destructiveness are clear. The description adds behavioral details: fans out to multiple sources, uses GDELT with GNews fallback on rate limits or errors, and notes USPTO soft-fails due to API sunset. Does not contradict annotations.

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

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

The description is fairly long but every sentence is informative. It is front-loaded with purpose and examples, then sources, then parameter usage, then alternative. The structure is logical though it could be slightly more compact (e.g., combining source list).

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 mentions the return structure: changes[] grouped by source, total_changes count, and citation URIs. It covers all three parameters with usage details, describes fallback and error behavior, and differentiates from the sibling tool. It is complete for the tool's complexity.

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

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

Schema description coverage is 100%, but the description adds value beyond schema by explaining that 'since' accepts ISO dates or relative shorthand ('7d', '3m', '1y') and recommending '30d' or '1m' for typical monitoring. It clarifies that 'value' can be a ticker or zero-padded CIK, and '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 starts with concrete query examples ('What's new with X', 'latest on Y') and clearly states the tool provides a change feed for a company in a time window, fanning out to SEC, news, and patents. It directly distinguishes from the sibling 'entity_profile' tool, making the purpose unmistakable.

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

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

Explicitly tells when to use this tool vs the sibling 'entity_profile' for static profiles. Gives example queries and explains fallback behavior for news (GDELT preferred, GNews when rate-limited). Provides best-practice for 'since' parameter ('30d' or '1m').

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`, but the description adds valuable behavioral details: scoped by identifier, persistence differences between authenticated users and anonymous sessions (24-hour memory). This goes beyond annotations without contradicting them.

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

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

The description is front-loaded with the primary purpose in the first sentence and efficiently covers usage, behavior, and companion tools. It is compact but could be slightly more structured (e.g., bullet points) for easier scanning, but overall it is fairly 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 no output schema, the description does not need to explain return values. It mentions scoping and persistence, and references companion tools. It is complete enough for an agent to understand the tool's context, though it implicitly assumes overwrite behavior (idempotent) which is consistent with the annotation but not explicitly stated.

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

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

Schema coverage is 100% with both parameters described. The description adds interpretive context (e.g., 'Memory key' examples and 'Value to store (any text — findings, addresses, preferences, notes)') and mentions the key-value pair scoping. This enriches the schema information beyond the basic descriptions.

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

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

The description uses specific verbs ('Save data the agent will need to reuse later') and clearly identifies the resource (data key-value pairs). It distinguishes from sibling tools `recall` and `forget` by explicitly mentioning pairing with them, making the tool's purpose unique and obvious.

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 usage context: 'when you discover something worth carrying forward' and gives concrete examples (resolved ticker, target address, user preference). It also mentions pairing with `recall` and `forget`. However, it does not explicitly state when not to use this tool, but the positive guidance is strong.

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

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

The description adds value beyond annotations by explaining that each call cascades through several lookup endpoints and replaces 2-3 manual lookups. This provides behavioral context about internal complexity and efficiency, which is not covered by 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 dense with useful information, but it could be more readable with bullet points or shorter sentences. However, it is appropriately sized and front-loaded with examples, making it reasonably 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?

Despite having no output schema, the description fully explains what each call returns (including URIs) and notes auto-disambiguation for company names. For a two-parameter tool, this provides complete contextual information sufficient for correct invocation.

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

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

The description enriches parameter semantics by detailing the output for each entity type (e.g., company returns ticker + CIK + company_name + URI) and accepting multiple input formats (ticker, CIK, name). This goes well beyond the schema's brief descriptions, which are already 100% covered.

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

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

The description clearly states that the tool resolves a user-spoken name to a canonical identifier, with specific examples ('What's the ticker for...'). It distinguishes itself from siblings by being the go-to for name-to-ID conversion, which no other tool does.

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

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

The description explicitly advises to 'Use FIRST whenever you have a name but need an ID', providing strong usage guidance. While it doesn't explicitly list when not to use it, the context makes it clear; a minor improvement would be to mention alternatives for searching, but the current guidance is sufficient.

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

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

Describes the probe process with ai_visibility_check, ranking, and output fields (score, confidence, signal density). Adds behavioral detail beyond annotations which already indicate safe read-only. No output schema, so description compensates.

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

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

Three sentences, front-loaded with main purpose, 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?

Covers purpose, process, output format, and use case. Lacks error or rate limit details, but annotations cover idempotency. Adequate for 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%, and description adds value for entities parameter by clarifying first entry is treated as subject for narrative. Other parameters well-covered in 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 verb 'Compare' and resource 'AI visibility across multiple entities side-by-side'. Distinguishes from sibling ai_visibility_check by emphasizing multi-entity comparison.

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

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

Explicitly says 'Useful for competitive AI-marketing audits' and gives example question. Implicitly indicates single entity should use ai_visibility_check, though does not explicitly state when not to use.

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

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

Discloses composite nature, partial failures with graceful degradation, and specific timeout behavior (5-30s for bundlephobia first measurement). Annotations already indicate readOnly and idempotent, and the description adds valuable behavioral context without contradiction.

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

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

The description is detailed but efficient, front-loaded with main purpose. Every sentence adds value, though it could be slightly shortened without losing clarity.

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

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

Given no output schema, the description thoroughly explains return fields (summary block, per-advisory detail, links, alternative versions). Also covers failure modes and ecosystem scope. Complete for a complex composite tool.

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

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

Schema coverage is 100% with both parameters described. The description repeats the schema's default behavior for version, adding no new 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 specifies a composite check for npm packages combining deps.dev and bundlephobia. It clearly states the verb ('scan'), resource ('dependency'), and distinguishes from siblings by being an npm-specific composite tool.

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

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

Explicitly tells when to use: when agent asks about safety, popularity, size, or cost. Also notes ecosystem limitation: NPM only, with alternatives for PyPI/Maven/Cargo/Go via 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 readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds no behavioral details beyond the bare statement. With annotations covering safety, a score of 3 is appropriate as description adds no extra 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?

Description is a single, short sentence with no fluff. However, it is too brief, lacking necessary details for proper tool usage.

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

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

Despite having 5 parameters and an output schema, the description offers no explanation of search behavior, result format, or what fields are searched. Incomplete for a tool of this complexity.

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

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

Schema has 0% description coverage for all 5 parameters. The description does not explain any parameter meanings or how they affect search. Examples in schema provide some context, but the description itself adds minimal value.

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

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

Description uses specific verb 'search' and resource 'instruments', clearly stating the action and target. However, it does not distinguish from sibling tools like 'search_within', 'filter', or 'validate_claim', which may have overlapping functionality.

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

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

No guidance on when to use this tool vs. alternatives, no prerequisites or limitations mentioned. For a search tool with many siblings, this is a significant gap.

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 only declare readOnly, idempotent, openWorld hints. The description adds rich behavioral details: BGE-base-en embeddings, cosine similarity over 500-char windows, 200k char cap with truncation, and that results include character offsets and similarity scores. This is far beyond annotation scope.

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

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

Single paragraph, no wasted sentences. Every sentence adds value: purpose, usage scenario, pairing hint, technical details ('BGE-base-en…'), and constraints ('200K chars'). Front-loaded with key action ('semantic search inside a fetched record').

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 explains return format (passages with offsets and scores). Covers truncation, embedding details, and pairing with another tool. For a search tool with three parameters, this covers all needed context.

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

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

Schema coverage is 100%, and the description adds meaning beyond schema: explains 'text' as document to search, gives example queries for 'query', and clarifies default behavior for 'limit' (1-20, default 5). The example query strings are particularly helpful.

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

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

The description clearly states it performs semantic search inside a fetched record, with specific examples (SEC 10-K, article, tool result). It contrasts with sibling tools like 'search' and explicitly mentions pairing with 'ask_pipeworx_grounded', making its purpose distinct.

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 to use when the record is too large for the prompt ('saves context') and suggests pairing with ask_pipeworx_grounded. It provides clear context without stating when not to use, but the usage scenario is well-defined.

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

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

Annotations (readOnlyHint=false, idempotentHint=true, etc.) are present. The description adds context like OAuth requirement, delivery channel behaviors (SMS cap, webhook auto-disable, one-time secret), which enriches behavioral understanding 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 well-structured with bullet points and examples, front-loading the purpose. It could be slightly more concise, but it earns its length through useful detail.

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

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

Despite no output schema, the description covers the return value (subscription ID), prerequisites, all parameter behaviors, delivery channels with limitations, and further reference endpoints. It is fully actionable.

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

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

With 100% schema coverage, the description still adds significant value by providing concrete examples for type-specific params, delivery constraints, and webhook security details, making parameter usage much clearer.

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, returns the subscription ID, and distinguishes from sibling tools like list_subscriptions and unsubscribe through its action verb and resource context.

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

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

The description specifies requirements (Pipeworx OAuth account, not for anonymous/BYO) and provides explicit usage examples for each subscription type, but lacks direct mention of when not to use this tool versus alternatives.

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

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

Annotations already indicate readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds significant behavioral context: it returns example questions from a live catalog, explains the output format, and provides specific usage patterns. No contradiction with annotations.

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

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

The description is a single, well-structured paragraph that front-loads common user queries and then explains functionality and usage. While it is packed with information, it could be slightly more concise; however, every sentence serves a purpose.

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

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

Given no output schema, the description thoroughly explains the return format (category-bucketed example questions with tool and argument shapes) and the effect of the topic parameter. It covers all necessary context for an agent to understand and use the tool correctly.

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

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

Schema coverage is 100% with a description for the single parameter 'topic'. The description adds meaning by explicitly listing the possible values ('finance', 'pharma', etc.) and explaining the effect of omitting the parameter (cross-category spread). It also clarifies that the result includes tool+argument shapes, which goes 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 returns category-bucketed example questions with tool and argument shapes, serving as an onboarding entry point. It distinguishes from siblings by specifying it's for when the user doesn't know what Pipeworx can do, and it lists the exact verbs and resources (e.g., 'returns', 'example questions').

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

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

Explicitly says to use this tool 'FIRST when you do not yet know what Pipeworx can do' and provides guidance on calling with no arguments for full spread or with a topic to focus. It also hints at alternatives like meta-tools (ask_pipeworx, entity_profile, etc.).

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 explains that the row is deactivated (not deleted) and historical events remain available via recent_alerts. This adds valuable behavioral context beyond the annotations.

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

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

Two sentences, each serving a distinct purpose: purpose statement and behavioral detail. No redundant information.

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

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

For a simple tool with one required parameter and no output schema, the description covers purpose, side effects, and constraint (ownership) adequately.

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

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

The only parameter 'id' is described in the schema as 'Subscription id (uuid) returned by subscribe.' The description doesn't add new information beyond that, so it meets the baseline for high schema coverage.

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

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

The description clearly states the tool cancels a subscription by id, which is specific and matches the tool name. It also mentions ownership enforcement, distinguishing it from general subscription management 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 specifies that ownership is enforced, implying you can only cancel your own subscriptions. It does not explicitly mention alternatives or when not to use, but the context is clear.

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

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

Annotations already declare readOnlyHint and idempotentHint. Description adds behavioral details: returns verdict, structured form, actual value with citation, and percent delta. No contradictions.

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

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

Description is well-structured, front-loaded with purpose and typical phrasing, then usage, scope, and outputs. Every sentence is informative 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?

Despite no output schema, description fully explains return types and limitations (scope to company-financial claims). Comprehensive for a single-parameter tool.

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

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

Schema coverage is 100%, baseline 3. Description adds value with natural-language claim examples and explains the input format, enhancing the schema's description.

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

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

Description clearly defines tool as natural-language claim verification against authoritative sources, with specific use cases like 'Is it true that…'. It distinguishes from siblings by noting it replaces multiple sequential calls.

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

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

Explicitly states when to use: 'Use whenever the agent needs to check whether something a user said is factually correct.' Context is clear, though it doesn't explicitly mention when not to use.

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