Data La

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

Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds valuable context: default model is free, using Anthropic requires a BYO key, and the return structure includes per-model details. This extends beyond the annotations nicely.

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, with the core action front-loaded. Every sentence adds value, and there is no unnecessary repetition. It fits the tool's complexity perfectly.

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 the tool's purpose, parameters, use cases, and return structure. It lacks detailed scoring methodology, but given no output schema, it provides sufficient context for an 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%, so baseline is 3. The description adds meaning by explaining the default model and the optional _apiKey requirement, enhancing understanding of the 'models' and '_apiKey' parameters beyond the schema descriptions.

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

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

The description clearly states the tool probes LLMs for knowledge about an entity and scores visibility (0-100). It specifies the action, resource, and output. However, it does not explicitly differentiate from similar sibling tools like 'scan_competitor_ai_presence', preventing a score of 5.

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 by listing scenarios: 'AI-marketing audits, pre-launch brand checks, competitive monitoring.' It does not explicitly state when not to use the tool or name alternatives, though the context is sufficient for decision-making.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds that it's a single fast call, works on every tier, and returns stable pipeworx:// citation URIs. It also mentions routing among 5,008 tools. No contradictions and adds useful behavioral context beyond annotations.

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

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

The description is verbose but well-structured with clear sections and front-loaded emphasis. Every sentence contributes, though it could be slightly more concise. Still, it's efficient for the complexity involved.

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 (routing to many sources) and many sibling tools, the description covers usage, examples, and alternatives comprehensively. No output schema but mentions return format with citation URIs. A model of completeness.

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

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

Schema coverage is 100% with parameter descriptions. The description adds examples and mentions aliases, but the schema already explains the 'question' parameter well. With baseline 3 for high coverage, the description provides marginal extra value.

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

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

The description clearly states the tool routes questions to a vast array of sources and returns structured answers with citations. It provides specific examples and contrasts with siblings, leaving no ambiguity about the tool's function.

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

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

The description explicitly prefers this tool over web search for factual questions, lists alternative tools for specific needs (grounded, deep research), and gives practical when-to-use guidance with example queries. No gaps.

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

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

Beyond annotations (readOnly, idempotent, non-destructive), description adds that it's a full working router with experimental improvements and falls back to nothing. Explains source-preference ranking behavior, adding useful 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 informative and well-structured, though slightly verbose. Every sentence adds value, but could be tightened 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?

Given the complexity (5,008 tools), description explains the differences from stable version and the source-preference ranking. Does not detail response shape (implied same as ask_pipeworx). Lacks mention of potential reliability trade-offs.

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

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

Schema description coverage is 100% with all aliases documented. Description does not add extra parameter meaning beyond the schema, so baseline 3 is appropriate.

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

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

Description clearly states it's a beta version of ask_pipeworx with identical tool set and response shape, but with candidate routing improvements enabled live. It specifies the source-preference ranking behavior and distinguishes from the stable sibling.

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 it exactly like ask_pipeworx when you want the newest routing' and notes that results are compared against stable router. Provides clear context for when to use, though lacks explicit 'do not use' conditions.

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

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

Beyond annotations (readOnlyHint, openWorldHint, etc.), the description adds refusal reasons, return format, cost implications (extra LLM call), and that it only uses the tool result. 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 purpose and includes essential details (refusal reasons, cost, when to use). Every sentence adds value, though slightly lengthy; still well-structured.

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

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

Given the tool's complexity and lack of output schema, the description is complete: it explains behavior, refusal reasons, return format, cost, and usage context. No gaps remain.

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

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

Schema coverage is 100% with 6 parameters all aliases for 'question'. The schema already describes them. The description does not add significant meaning beyond confirming aliases, so baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose: 'Hallucination-resistant answer mode for high-stakes reads.' It specifies that it picks the right tool, fetches data, and extracts answers only from the tool result, distinguishing it from the sibling ask_pipeworx.

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

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

The description explicitly states when to use: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts.' It also advises preferring ask_pipeworx for casual lookups, providing clear guidance on 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?

Despite annotations already indicating readOnlyHint=true and idempotentHint=true, the description adds exhaustive behavioral context: classification logic, fan-out examples, cancellation rule parsing, error handling (GDELT 429s with backfill), and safety short-circuits. It goes far beyond the annotations and discloses non-obvious behaviors that an agent must know.

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

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

The description is very detailed but overly long. It uses a stream-of-consciousness style with CAPS headers and includes many examples that, while helpful, contribute to verbosity. The first few sentences establish the purpose, but the rest is dense. A more structured, concise format would improve readability without losing information.

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

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

Given the tool's complexity (multiple data sources, classification, edge cases) and the absence of an output schema, the description is remarkably complete. It explains all major behaviors, response shapes, resolver contract, parent_event extraction, news fallback, safety mechanisms, and cancellation rules. An agent can fully understand inputs, outputs, and failure modes.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds value by elaborating on the 'depth' parameter (quick vs thorough fan-out) and the 'include_raw' parameter (when to use true/false, file size implications). It also gives additional examples for the 'market' parameter. However, the descriptions in the schema already cover the basics, so the added value is moderate.

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

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

The description starts with a clear action verb ('Research') and specific resource ('Polymarket bet'), and immediately distinguishes itself from siblings by detailing its multi-step process (resolve, classify, fan-out, evidence packet). It gives concrete examples of usage ('should I bet on X') and input formats, leaving no ambiguity about what the 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 states when to use the tool ('Use for ...') and provides guidance on inspecting match confidence before trusting results. It explains scenarios that lead to early returns (low confidence, closed market). While it doesn't explicitly state when not to use it, the context is sufficient for an agent to decide.

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

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

Description adds significant context beyond annotations: it makes one parallel call, handles off-calendar fiscal years, sorts results by primary metric, and returns paired data with citation URIs. Annotations already indicate readOnly, openWorld, idempotent, non-destructive.

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

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

The description is a single dense paragraph that efficiently conveys purpose, usage, and details. It could benefit from bullet points for readability, but it is not unnecessarily verbose.

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

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

Covers both entity types, explains return data and sorting, and includes citation URIs. Without an output schema, it adequately describes what the agent can expect. Minor omission: no mention of error handling or rate limits, but annotations cover openWorld hint.

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

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

Despite 100% schema coverage, the description enriches parameter meaning by detailing that 'type' determines whether financial data from SEC EDGAR/XBRL or drug data from FAERS/FDA is pulled, and that 'values' are tickers/CIKs for companies or drug names.

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

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

Description clearly states it performs side-by-side comparison of 2-5 entities in a single call, distinguishes from sequential lookups, and includes example query patterns. The verb 'compare' and resource 'entities' are specific.

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 'ALWAYS PREFER over sequential single-pack lookups when comparing entities' and provides example query phrases. It also specifies what data each type pulls, guiding appropriate 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?

Annotations already indicate read-only, open-world, idempotent, non-destructive. The description adds extensive behavioral context: account required, NOT open-web search, parallel routing, return format with evidence/confidence/source/citation/gaps/contradictions, timing 15-90s, hop field, semantic excerpts. 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 long but well-structured: starts with account requirement, then core functionality, usage guidance, depth details, return format, timing. Front-loaded with critical information. Some redundancy (e.g., contradiction mentioned twice) but overall efficient for the complexity.

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

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

Given no output schema, the description fully explains return format (findings packet with evidence, confidence, source, fetched_at, citations, gaps[], contradictions[], hop field). Covers prerequisites, depth behavior, timing, and edge cases like gaps and contradictions. Comprehensive for a research tool with complex behavior.

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

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

Schema covers both parameters with descriptions, but the description adds meaning: depth levels are explained (quick=3, standard=5, thorough=8) with details on hop behavior and contradiction scans. Question parameter is clarified as broad/multi-part acceptable. Schema coverage 100% but description enriches 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 performs 'grounded multi-source research across Pipeworx's 1318 structured data sources' and distinguishes it from siblings like ask_pipeworx by specifying it decomposes questions into facets and returns a findings packet. It uses specific verbs like 'researches' and highlights the unique parallel routing to 5,008 tools.

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

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

Explicitly states when to use (broad/multi-part questions over structured data) and when not to (single lookups or breaking news, directing to ask_pipeworx). Provides alternatives and mentions account requirements and paid tier for 'thorough' depth.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the description adds value by explaining the return format (top-N most relevant with full schemas and examples) and that results are ready to call directly.

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

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

The description is dense but well-structured, front-loading purpose and usage guidance. Every sentence adds value, though it could be slightly trimmed without losing essential information.

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

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

Despite no output schema, the description fully explains what the tool returns (top-N tools with names, descriptions, full schemas, and examples). Given the broad domain list and the tool's role as a discovery gateway, it is contextually complete.

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

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

Schema coverage is 100% with well-described parameters. The description augments by clarifying that 'query' accepts aliases (task, q, description, search) and provides two natural language examples, adding meaning beyond the schema.

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

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

The description clearly states the tool's purpose: 'Find tools by describing the data or task.' It specifies a range of domains (SEC filings, FDA drugs, etc.) and distinguishes itself from sibling tools by being the discovery entry point.

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 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' Also provides context for when to use ('browse, search, look up, or discover what tools exist').

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds behavioral traits beyond annotations: details on data sources (SEC, XBRL, USPTO, news, GLEIF), soft-fail for patents, and return structure (cik, filings, fundamentals, etc.). 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 front-loaded with example queries for quick understanding. While somewhat long, each sentence adds value: examples, preference guidance, data sources, return fields, and limitations. Minor redundancy in mentioning 'names not supported' twice.

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 thoroughly explains what is returned: company info, recent filings, fundamentals, patents, news, LEI. Covers edge cases (soft-fail for patents, name resolution requirement). Completely addresses agent needs for this complex 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%, but description adds meaning beyond schema: clarifies that 'type' must be 'company' (only supported today), explains 'value' can be ticker or zero-padded CIK, and stresses that names are not supported. This helps the agent use parameters correctly.

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

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

Description clearly states the tool's purpose: provide a full cross-source profile of a US public company. It uses specific verbs like 'tell me about' and 'brief me on', and distinguishes itself from siblings like 'resolve_entity' and 'compare_entities' by emphasizing it's the preferred tool for holistic views.

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 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups' and mentions when not to use it (names not supported, use resolve_entity first). Provides clear context for when this tool is appropriate.

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

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

Annotations already indicate destructive (destructiveHint=true) and idempotent (idempotentHint=true) behavior. The description adds context about clearing sensitive data 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?

Three sentences with no extraneous information; front-loaded with the core purpose.

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

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

For a simple tool with one parameter and no output schema, the description fully covers when, why, and how to use it.

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

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

Schema covers 100% of parameter descriptions (key: 'Memory key to delete'), so the description adds no additional meaning beyond the schema.

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

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

The description clearly states the action ('Delete'), the resource ('previously stored memory by key'), and distinguishes from siblings by noting pairing with 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 specifies when to use: 'when context is stale, the task is done, or you want to clear sensitive data', and suggests pairing with remember and recall as 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 read-only, open-world, idempotent, non-destructive. Description adds operational detail (fetches page, extracts title/description/key links, emits markdown) without contradicting 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 well-structured sentences that front-load the purpose and provide essential details without unnecessary elaboration.

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 (2 params, no output schema), the description covers input, output format, and use cases 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?

Schema description coverage is 100% and already includes parameter descriptions. Description adds minimal extra value (e.g., example URL format) 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 specifies the action ('generate') and resource ('llms.txt file'), with context of output format and use cases. Distinguishes from sibling tools by its unique focus on AI crawler indexing.

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

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

Provides explicit usage scenarios (client indexing, personal project, competitor audit) but does not explicitly state when not to use or mention alternative tools among siblings.

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

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

Annotations provide readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false. The description adds behavioral details: it uses Socrata API, and optional API key for higher rate limits. No contradictions.

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

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

Two sentences, first sentence states purpose and action, second explains output and use. No fluff, front-loaded, every sentence is valuable.

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

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

The description fully explains the tool's function, output, and how to use the result with a sibling tool. Given no output schema, the description provides necessary detail. Annotations cover safety and behavior. Completeness is high.

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 description does not need to add much. It adds context that the returned ID can be used with la_query, which is helpful for understanding the output but not directly parameter semantics. Baseline score 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 uses specific verb 'Search' and identifies the resource as 'Los Angeles open-data catalogue (data.lacity.org)'. It explains what is returned (dataset names, descriptions, Socrata resource ids) and distinguishes from sibling tools like la_query and la_recent by specifying the output as resource ids for use with la_query.

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 clearly states when to use the tool: to search by keyword for datasets. It implies when not to use it by mentioning that returned IDs can be passed to la_query, suggesting that direct data querying should use that sibling. It does not explicitly state exclusions but provides sufficient 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 provide readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds that it runs a raw SoQL query with full SoQL clauses, and mentions optional API key for rate limits, no contradictions.

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

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

Two sentences, no wasted words, critical information (What, How, Where to find resource IDs) is front-loaded. Ideal conciseness.

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

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

Despite no output schema and 8 parameters, the description covers purpose, usage, parameter semantics, and relationships to sibling tools, making it fully adequate for an AI 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?

All parameters have schema descriptions (100% coverage). Description adds context: resource_id example '2nrs-mtv8', defaults like limit (100 max 5000), and clarifies SoQL clause usage (where/select/group/order/limit/offset).

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 'Run a raw SoQL query against any Los Angeles open-data resource' with a specific verb (run) and resource (SoQL query on data.lacity.org). It distinguishes from siblings like la_datasets and la_recent by name and purpose.

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

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

Explicitly tells when to use alternatives: 'Use la_datasets to find a resource id, or la_recent for the common ones.' Also implies when to use this tool by describing its capabilities.

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

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

Annotations already provide readOnlyHint, idempotentHint, openWorldHint, and destructiveHint. The description adds behavioral context: returns newest-first rows, and the 311 dataset is partitioned by year. This adds value beyond annotations, though annotations cover the core safety profile.

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

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

The description is concise (6 sentences) and well-structured: purpose, usage guidance, dataset names, return behavior, filter instruction, and a caveat. Every sentence adds value, no redundancy.

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

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

No output schema exists, but the description does not detail return format beyond 'rows' and ordering. However, the datasets are well-known public datasets, and the tool is simple. The note about 311 partitioning adds completeness. Could be improved by mentioning the record structure, but adequate for its scope.

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

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

Schema covers 100% of parameters with descriptions. The description adds context: explains the 'where' parameter as a SoQL filter, provides example filter syntax, and clarifies the dataset enum values. It also notes the default limit and optional API key usage. This adds meaning beyond the schema.

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

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

The description clearly states the tool returns recent records from LA open datasets by friendly name, listing the specific datasets (crime, arrests, businesses, permits, 311). It distinguishes itself from siblings like la_query (for complex queries) and la_datasets (for other years).

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 'PREFER OVER WEB SEARCH' for common queries and 'for anything else use la_query'. Also includes a note about LA 311 partitioning and alternative tool for other years. This provides clear when-to-use and when-not-to-use guidance with named 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 provide readOnlyHint=true, idempotentHint=true, etc. Description adds the list of returned fields 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?

Two concise sentences: first states purpose and output fields, second gives usage guidance. No wasted words.

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

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

Simple tool with 0 required params and 1 optional. Description covers purpose, return fields, and usage context adequately 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%, so parameter is fully documented in schema. Description does not add further meaning to the parameter.

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

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

Clearly states 'List the caller's active subscriptions' with specific verb and resource. Distinguishes from siblings like subscribe and unsubscribe by focusing on listing.

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: 'before adding more or to find an id to cancel.' Provides clear context, though no explicit when-not-to-use.

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

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

Discloses rate limit (5 per identifier per day), cost (free, doesn't count against quota), and roadmap impact. These details are beyond the annotations, which only indicate readOnlyHint, openWorldHint, etc., and none contradict the description.

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

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

The description is a single, well-structured paragraph that front-loads the action ('Tell the Pipeworx team') and quickly covers purpose, usage scenarios, writing guidelines, and behavioral constraints. Every sentence adds value with no redundancy.

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

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

The description fully explains the tool's purpose and constraints despite the lack of an output schema. It covers parameter usage, rate limits, and roadmap impact. Minor omission: does not mention whether the user receives confirmation after sending, but this is acceptable for a feedback 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?

The input schema has 100% coverage for parameter descriptions, but the description adds extra value by explaining the type enum values, suggesting message length (1-2 sentences, 2000 chars max), and emphasizing specificity. This goes beyond the schema's basic descriptions.

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

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

The description clearly states the tool's purpose: sending feedback to the Pipeworx team about bugs, feature requests, data gaps, or praise. It distinguishes itself from sibling tools by focusing on feedback collection rather than data retrieval or analysis.

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

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

Explicitly specifies when to use the tool (e.g., 'when a tool returns wrong/stale data') and what not to do ('don't paste the end-user's prompt'). Provides clear context for each feedback type and directs users to describe issues in terms of Pipeworx tools/packs.

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

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

Beyond annotations (readOnly, idempotent, non-destructive), the description adds caching behavior (5min-1h), data source (CF analytics-engine), no PII, and output structure (pack, tool, count). This provides useful context for an agent.

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 (4-5 lines), uses bullet points for use cases, and front-loads the core purpose. Every sentence provides 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?

Given the tool's simplicity (1 param, no output schema, rich annotations), the description is complete: it covers purpose, usage scenarios, data source, caching, privacy, and behavior across windows. No gaps remain.

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

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

Schema description coverage is 100%, and the inline parameter description already explains the enum values and their interpretation. The tool description repeats this but adds no new information beyond the schema, so a baseline of 3 is appropriate.

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

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

The description clearly states the tool returns top tools, packs, and call volume over a window, with three explicit use cases. It distinguishes itself from sibling tools like discover_tools by focusing on real-time agent usage trends.

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 specific use cases are provided (discovery, confirmation, alignment), offering clear when-to-use guidance. However, it does not explicitly mention alternatives or when not to use this tool.

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

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

Annotations (readOnly, idempotent) are reinforced and extended: details scanning behavior, Jaccard similarity filter, placeholder fraction filter, fill check against CLOB depth, and response structure. No contradictions.

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

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

Somewhat lengthy but every sentence adds value; well-structured with front-loaded purpose, detailed mode explanations, filters, response format, and fill check. Minor redundancy could be trimmed, but overall efficient.

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

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

Given no output schema, description fully explains return values: opportunities array fields, partition_check fields, fill check criteria. Also covers edge cases (placeholder filters, similarity threshold, thin legs). Complete for a complex arbitrage detection 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?

Two optional params with 100% schema coverage; description adds significant meaning: explains trending scan (no args), event mode walk-through, topic mode cross-event scanning with similarity filter, and response fields. Far exceeds schema's brief descriptions.

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

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

The description clearly states the tool finds arbitrage opportunities on Polymarket using monotonicity violations and partition-sum checks. It distinguishes two modes (event, topic) and a no-arg trending scan, making it distinct from siblings like polymarket_edges or polymarket_fill_risk.

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: call with no args for trending scan, pass event for per-event partition check (recommended), or topic for cross-event scan. Warns when not to trade (realizable edge ≤ 0) and directs to sibling polymarket_fill_risk for custom sizing.

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

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

Disclosures beyond annotations include caching behavior ('Cached 1h at the KV level keyed on all knobs'), response structure (by_segment, diagnostics), and edge computation details (e.g., slippage, Kelly sizing). Annotations already indicate read-only, but description adds significant behavioral context.

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

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

The description is comprehensive but verbose, packing many details into a single paragraph. It is structured with segments and bullet points, but could be more concise. Front-loaded with purpose, but overall length reduces readability.

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

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

Given 9 parameters, three model families, and a complex response without output schema, the description is thorough. It covers caching, response top-level fields, diagnostics, parameter knobs, and edge computation rationale, ensuring the agent understands the tool fully.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining parameter interactions (e.g., min_partition_leg_kelly clarifies that partition arbs bypass min_kelly) and providing context like 'Polymarket has zero trading fees as of 2024 but bid/ask + thin depth typically eats 20-50bp per trade.'

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 scans Polymarket markets for opportunities where Pipeworx data disagrees with market price. It distinguishes from sibling tools like polymarket_arbitrage and polymarket_edge_tracker by focusing on model-driven and structural arbitrage edges.

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

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

Provides explicit context: 'Built for what should I bet on today — agents discover opportunities without paging hundreds of markets.' It implies use case but does not explicitly exclude alternatives or mention when not to use. Clear context without exclusions.

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

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

The description goes beyond the annotations by detailing that data comes from daily snapshots bounded by a 60-day TTL and that decay numbers are computed from daily closes (not intraday). This provides essential context for understanding data freshness and limitations.

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 longer than typical but all sentences are relevant and informative. It is front-loaded with the core purpose and structured logically from purpose to output details to limitations.

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

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

Despite lacking an output schema, the description fully documents the return structure (tracked, expired, snapshot_dates) with field details. It also covers edge cases like gaps in snapshots. This level of detail is sufficient for an agent to use the tool correctly.

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

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

The schema already describes both parameters with coverage. The description adds value by stating defaults (14 days, 1wk), maximum for days (30), and explaining that the window parameter selects a snapshot family. This enriches the agent's understanding beyond the schema.

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

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

The description explicitly states that the tool provides edge persistence and decay telemetry from daily snapshots, answering how long an edge has existed and whether it is shrinking. This distinguishes it from sibling tools like polymarket_edges, which likely provide current edge data.

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

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

The description provides clear context on when to use the tool by explaining the significance of edge age ('a fresh wide edge and a 3-week-old wide edge are different trades'). However, it does not explicitly name alternatives or specify when not to use it, which slightly reduces the score.

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, so the description's job is to add behavioral context. It does so by detailing the ladder walking, return fields, and edge cases like thin_legs and forced_directional_risk, which go beyond what annotations provide.

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

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

The description is long but well-structured with clear sections for required params, single-market, and basket. The core purpose is front-loaded, and every sentence provides essential context. No superfluous 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 no output schema, the description lists all return fields for both modes (top_of_book, vwap_fill_price, slippage_pp, etc.) and explains edge cases (thin_legs, forced_directional_risk). Given the tool's complexity and lack of output schema, this is highly 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%, baseline is 3. The description adds meaning by explaining the different interpretations of side, market, event, and size_usd in single-market vs basket modes, including defaults and clamping (10–1,000,000). This adds value beyond the schema.

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

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

The description clearly states it performs a realizable-vs-theoretical edge check against live CLOB order-book depth. It distinguishes between single-market and basket modes with specific examples, which differentiates it from sibling tools like polymarket_arbitrage and polymarket_edges.

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

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

Explicit instructions say 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500' and warns against partial basket fills converting an arb into an unhedged directional position. 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 indicate readOnly, idempotent, not destructive. The description adds extensive behavioral details: compatibility_warning conditions, temporal_alignment, skipped counters, and the significance of matched_pairs. 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 information-dense but somewhat lengthy. However, it is well-structured with clear sections (purpose, modes, response, safety fields). 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?

With no output schema, the description explains the response format in detail (leg-by-leg prices, top_spreads_pp, safety fields). It covers all aspects needed for an agent to understand and use the tool 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%. The description adds meaning beyond schema by explaining the overriding behavior of explicit parameters and listing all ten topic shortcuts. It clarifies how each parameter affects data retrieval.

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

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

The description clearly states the tool computes cross-venue spreads between Kalshi and Polymarket for the same resolving question. It distinguishes itself from siblings like 'polymarket_arbitrage' by focusing on spread analysis and explicitly mentioning two modes.

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

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

The description explains two modes (topic shortcuts vs explicit tickers) and provides strong usage guidance, including warnings that most pre-mapped topics are not tradeable and that compatibility warnings should be heeded.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds non-obvious context: scoping to identifier (IP, key hash, account ID) and pairs with remember/forget. No contradictions.

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

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

Three sentences, front-loaded with action, no wasted words. Every sentence adds value.

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

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

Given the low complexity (1 param, no output schema, annotations present), the description completely covers purpose, usage, and scoping. No gaps.

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

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

Schema coverage is 100% and the schema already explains that omitting key lists all. The description merely restates this, adding no new meaning beyond the schema.

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

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

The description clearly states the verb (retrieve/list), resource (saved values), and distinguishes from siblings like remember and forget by naming them. It specifies the exact functionality: retrieve a value by key or list all keys.

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

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

The description explicitly says when to use it: to look up previously stored context such as ticker, address, or research notes. It also mentions scoping but lacks explicit 'when not to use' guidance. Overall clear usage context.

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

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

The description states that setting mark_read:true flags events as read, which is a mutation. This contradicts the readOnlyHint=true annotation, indicating a serious inconsistency. No additional behavioral details like authorization or rate limits are disclosed.

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

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

The description is concise (5 sentences), well-structured, and front-loaded. Every sentence provides essential information: purpose, return fields, filtering, side-effect, and alternative access. No waste.

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 annotations and no output schema, the description adequately covers return fields, parameter usage, and alternative access. It lacks information on error handling or empty results, but overall it is sufficient for a tool with 5 parameters and simple behavior.

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

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

Schema coverage is 100%, and the description adds value by providing examples (e.g., 'sec_8k' for type) and clarifying behavior (e.g., effect of mark_read, ISO format for since). This exceeds 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?

Description clearly states 'Pull fired events from your subscription feed' and specifies return fields and filtering options. It uses specific verbs and resource. However, it does not explicitly differentiate from sibling tools like 'recent_changes' or 'la_recent', so a 4 is appropriate.

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 some guidance by mentioning that polling works and an alternate direct GET endpoint exists. However, it does not clearly state when to use this tool versus alternatives, nor does it specify when not to use it.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive. The description adds significant behavioral context: fans out to multiple sources (SEC, GDELT/GNews, USPTO), explains fallback logic, date parsing, output structure (changes[] grouped by source + total_changes + URIs), and known failure modes (USPTO soft-fails). 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 dense but every sentence adds essential information: purpose, usage, parameters, sources, fallback, and output format. It is front-loaded with common queries and ends with a clear alternative tool reference. No fluff.

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

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

Despite no output schema, the description fully explains the return structure (changes[] grouped by source + total_changes + URIs). It covers all necessary context: sources, fallbacks, date formats, input validation, and relationship to sibling 'entity_profile'. Sufficient for an agent to correctly invoke and interpret results.

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

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

Schema description coverage is 100% (all 3 parameters have descriptions). The description adds meaning beyond schema: examples of relative shorthand for 'since' (e.g., '7d', '30d'), explanation that 'value' can be ticker or CIK, and clarification that 'type' only supports 'company' currently.

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 with concrete examples of queries ('What's new with X', 'latest on Y') and explicitly distinguishes it from sibling 'entity_profile' which provides static profile instead of a change feed. The verb 'recent_changes' and resource 'company' are specific.

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

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

The description explicitly provides when to use (monitoring a company for recent changes in a time window) and when not to use ('Use entity_profile instead when you want the static profile...'). It also details fallback behavior (GDELT→GNews) and date format choices (ISO or relative shorthand).

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 adds context beyond annotations: key-value pair scoped by identifier, 24-hour expiration for anonymous sessions. Aligns with idempotentHint and adds useful behavioral details.

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

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

Five sentences with no wasted words. Front-loaded with purpose, followed by usage, then technical details. Efficient and well-structured.

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

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

Tool is simple with no output schema; description covers when, why, and how. Could mention return value (e.g., success confirmation), but not essential. Overall, complete for the tool's complexity.

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

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

Schema coverage is 100%, but description adds meaningful examples for key and value, enhancing understanding of what to store. No enums or nested objects; parameter meaning is clear.

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 purpose: saving data for later reuse. It provides specific examples (resolved ticker, target address) and distinguishes from sibling tools 'recall' and 'forget'.

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

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

Explicit guidance on when to use ('when you discover something worth carrying forward') and mentions alternatives ('Pair with recall to retrieve later, forget to delete'). Also explains persistence differences based on authentication.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds valuable behavior: it cascades through multiple endpoints and replaces manual lookups. 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, front-loaded with example queries, and every sentence adds value. No unnecessary words.

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

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

Given two parameters, high schema coverage, no output schema, and rich annotations, the description is comprehensive: it explains return values (ticker + CIK, RxCUI) and citation URIs for both entity types, and instructs the agent on when to use.

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

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

Schema coverage is 100% with enum and descriptions. The description enriches parameters by explaining supported types and providing examples for values (e.g., 'AAPL', 'ozempic'), and adds 'auto-disambiguated' context.

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

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

The description clearly states the tool resolves names to canonical identifiers, provides concrete examples (ticker, CIK, RxCUI), and differentiates from siblings by instructing 'Use FIRST whenever you have a name but need an ID.'

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

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

The description explicitly says when to use the tool ('when you have a name but need an ID') and provides contextual examples. It does not explicitly state when not to use it, but the context is clear enough 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 already declare readOnlyHint, idempotentHint, and destructiveHint, so the description adds value by detailing how the tool probes each entity, ranks, and returns specific fields (score, confidence, signal density). No contradictions with annotations.

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

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

The description is concise and front-loaded, with the first sentence stating the core purpose, followed by mechanics, use case, and output details. 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?

Despite no output schema, the description explains the return format (ranked list with score, confidence, signal density). It covers optional parameters and their roles, making it fairly complete for a 4-parameter tool with moderate complexity.

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

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

Schema coverage is 100% with all parameters described, but the description adds meaningful context beyond the schema, such as treating the first entity as the 'subject' for narrative and explaining the relationship between models and _apiKey. This additional semantics justifies a score above baseline 3.

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

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

The description clearly states the tool compares AI visibility across multiple entities side-by-side, specifying it probes each entity with ai_visibility_check, ranks by score, and surfaces most/least recognized. It effectively distinguishes from the sibling tool ai_visibility_check, which is single-entity.

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

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

The description explicitly provides a use case ('competitive AI-marketing audits') and an example question, implicitly contrasting with single-entity tool. It does not include explicit when-not-to-use scenarios but provides clear context for when this tool is appropriate.

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

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

Annotations already indicate read-only, open-world, idempotent. Description adds critical behavioral detail: 'bundlephobia's first measurement on a new version can take 5-30s; sources_failed will list it if it times out, the rest still returns.' No contradiction with annotations.

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

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

Description is dense but well-structured, front-loading core function and use case. Every sentence adds value, though slightly long for its information density; still 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?

Covers tool purpose, use cases, output fields, constraints, partial failures, and ecosystem limitations. Without output schema, the description sufficiently details return values and behavior.

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

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

Schema coverage is 100%, and description adds context: accepts scoped packages, defaults to latest version. Enhances schema without redundancy.

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

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

Description clearly states it is a composite check for npm package evaluation, listing specific sources and outputs. Distinguishes from siblings by being focused on npm dependency analysis, while siblings like 'deep_research' or 'entity_profile' serve different purposes.

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

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

Explicitly says 'Use whenever an agent asks is X safe/popular/small' and provides limitations: 'NPM ecosystem only in v1; PyPI/Maven/Cargo/Go fall under deps.dev:version directly.' Also explains partial failure behavior, guiding appropriate 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?

Annotations already declare readOnly, idempotent, non-destructive. Description adds critical behavioral details: truncation at 200K chars with flag, BGE-base-en embeddings, cosine similarity, 500-char overlapping windows, and return fields (passages with offsets and scores). 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?

Compact and information-dense. Each sentence adds value: purpose, usage guidance, technical details, and pairing suggestion. No wasted words, well-organized.

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

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

No output schema, but description fully explains return format (passages with offsets and similarity scores). Covers embedding model, window size, truncation, and pairing strategy. Complete for a semantic search tool.

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

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

Schema coverage is 100%, so baseline is 3. Description adds value beyond schema by providing natural-language query examples and clarifying truncation behavior for the text parameter. Slightly exceeds the baseline.

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

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

Clear verb+resource: 'semantic search INSIDE a fetched record.' Distinguishes from sibling tools by specifying it operates on already-fetched text and pairs with ask_pipeworx_grounded.

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 the record is too big to cram into the prompt.' Provides context of saving context and returning only relevant passages. Mentions pairing with a sibling tool for grounded answering. No explicit 'when not to use' but context 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?

Adds rich behavioral details beyond annotations: constraints on SMS (10/day cap, phone verification), webhook auto-disable after 10 failures, and that anonymous/BYO cannot persist. No contradiction with annotations.

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

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

Well-structured and front-loaded, but slightly verbose with detailed examples. Could be trimmed by 10-15% 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?

Comprehensively covers all subscription types, delivery channels, and constraints including verification steps and caps. Handles the complexity well despite missing 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?

Description adds significant context to the schema, with examples for each subscription type's params and delivery options, including required fields and constraints (e.g., sponsor or condition required for clinical_trial). Schema coverage is 100% but description still adds 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?

Clearly defines the tool as creating a proactive monitoring subscription to live-data event streams, returning a subscription ID. Distinguishes from sibling tools like list_subscriptions and unsubscribe by focusing on creation.

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 with examples for each subscription type, and prerequisites (Pipeworx OAuth account, verified phone for SMS). Lacks explicit guidance on when not to use but context implies alternatives like recent_alerts for pulling.

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, etc. The description adds behavioral details: the tool returns example questions with exact tool+argument shapes from a live catalog, and mentions optional topic filtering. 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 fairly long but each sentence adds value. It front-loads with alternative questions. Could be slightly more concise, but overall efficient.

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

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

For a tool with one parameter and no output schema, the description fully explains purpose, usage context, return content, and behavior. Annotations cover safety. Complete for its complexity.

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

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

Schema coverage is 100% with one parameter. The description adds meaning by listing example values for 'topic' ('finance', 'pharma', 'betting') and explaining how omission yields a cross-category spread, enriching the schema.

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

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

The description clearly identifies the tool as the onboarding entry point, stating it returns category-bucketed example questions and tool calls. It distinguishes from siblings by positioning it as the first tool to use when connecting.

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: 'Use this FIRST when you do not yet know what Pipeworx can do for you.' Also describes calling with no arguments for full spread or passing a topic for focus, implying when not to use (when already familiar).

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 context beyond annotations: ownership enforcement and soft-deactivation with historical availability. No contradiction with annotations (idempotentHint, destructiveHint).

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 short sentences, front-loaded with purpose, followed by ownership and behavioral detail. No wasted words.

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

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

Covers purpose, restrictions, and effect. Missing explicit return value or error handling, but adequate for a simple cancellation tool with 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?

Only one parameter 'id', schema already describes it as 'Subscription id (uuid) returned by subscribe'. Description adds little extra beyond 'by id'.

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

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

The description clearly states 'Cancel a subscription by id', using a specific verb and resource. It distinguishes from sibling tools like subscribe and list_subscriptions.

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

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

Explicitly says 'Ownership is enforced — you can only cancel your own subscriptions', providing clear when-to-use guidance. Also explains the effect deactivates the row, not deletes, relating to recent_alerts.

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

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

The description discloses behavioral traits beyond the annotations: it explains the dual pipeline (structured SEC path vs. grounded path), the verdict categories (confirmed, refuted, etc.), and the output includes citations. 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 actionable trigger phrases and packs significant detail (pipelines, verdicts, citations) into a compact structure. 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?

Given the two parameters with full schema coverage, the strong annotations, and no output schema needed, the description fully meets the needs. It explains the dual verification approach, verdict types, and output format, leaving no gaps for an AI agent.

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

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

The input schema already provides descriptions for both parameters (claim and tolerance_pct), achieving 100% coverage. The description adds meaningful context, such as the default behavior of tolerance_pct and its use for hallucination detection, enriching understanding beyond the schema.

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

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

The description uses specific trigger phrases like 'Is it true that…' and 'fact check' to clearly state the tool's purpose: verifying natural-language claims against authoritative sources. It distinguishes between company-financial claims (SEC EDGAR fast path) and other claims (grounded pipeline), differentiating it from sibling tools like deep_research or compare_entities.

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

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

The description provides explicit when-to-use guidance with example queries and explains the automated routing between two verification pipelines. While it doesn't explicitly list when-not-to-use or alternatives, the scope is clearly delineated (factual claims), making it easy for an agent to decide.

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