Texas Open Data

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

Annotations declare readOnly, openWorld, idempotent, non-destructive. Description adds behavioral details: per-model return structure (score, confidence, signals, raw_response) plus combined view, and cost implications (free vs BYO key). 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?

Approximately 100 words, well-structured: action first, then detail on models and return, finally use cases. Every sentence is substantive with no redundancies.

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

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

Despite no output schema, description sufficiently explains return structure (per-model and combined). Four parameters fully described in schema and enriched in description. No missing context for effective 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 descriptions for all 4 parameters. Description adds value by noting default model for 'models', explaining '_apiKey' is passed straight through to Anthropic, and that 'context' disambiguates common 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 probes LLMs for knowledge about an entity and scores visibility (0-100) per model. Specific verb 'probe' and resource 'LLMs' with outcome 'score visibility'. Distinguishes from sibling tools like scan_competitor_ai_presence by focusing on per-model visibility scoring.

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

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

Explicitly notes usefulness for AI-marketing audits, pre-launch brand checks, competitive monitoring. Explains default model (free) and when to provide Anthropic key. Lacks explicit when-not-to-use or alternatives, but context is clear enough.

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. Description adds behavioral context: it routes to 4552 tools, returns structured data with stable citation URIs, works on all tiers, and is fast. No contradictions. Minor omission of potential failure modes or rate limits.

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

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

Description is informative but somewhat lengthy. It is well-structured with front-loaded emphasis ('PREFER OVER WEB SEARCH'). Every sentence adds value, though a few could be tightened. Good use of examples and logical flow.

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 tools), the description is remarkably complete. It covers purpose, usage, alternatives, example queries, and expected output (structured answer with citations). No output schema exists, so description compensates well.

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

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

Schema coverage is 100% with descriptions for all 6 parameters. Description adds value beyond schema by explaining how to phrase questions, providing examples, and clarifying the range of supported queries. The aliases are also clarified.

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 routes questions to many specialized tools and returns structured answers with citations. It distinguishes itself from siblings like ask_pipeworx_grounded and deep_research. Lists specific domains and example queries, making the purpose unambiguous.

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

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

Explicitly says 'PREFER OVER WEB SEARCH' and gives clear when-to-use criteria for factual questions. Provides examples. Also specifies when to step up to alternative tools (grounded for hallucination-resistance, deep_research for broad questions). Includes when to use for breaking news.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds valuable behavioral context: extraction uses only tool result (no invention), returns explicit refusal reasons, and costs an extra LLM call. No contradiction with annotations.

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

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

Description is well-structured with key info front-loaded, uses bullet points for return fields, and each sentence serves a purpose. Slightly verbose but not wasteful; still concise 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 the tool's complexity (routing across 4,552 tools/1160 sources, extracting answers) and lack of output schema, the description fully explains return format ({answer, evidence, confidence, source...}) and refusal reasons. It also covers cost trade-off, making it complete for agent decision-making.

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

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

Schema coverage is 100% with descriptions for all 6 parameters (question and its aliases). The description does not add new parameter-specific meaning beyond what the schema provides, so baseline 3 is appropriate.

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

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

Description clearly states it is a 'hallucination-resistant answer mode for high-stakes reads', specifies the process (routing, fetching, extracting using only tool result), and distinguishes from sibling ask_pipeworx by noting the extra LLM call and use case (when answers will be quoted/cited). Verb+resource is clear and differentiated.

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

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

Explicitly says 'Use whenever an answer will be quoted, cited, or acted on...' and gives concrete examples (financial verdicts, legal claims). Also provides when NOT to use: 'prefer ask_pipeworx for casual lookups', including cost trade-off. This is excellent guidance on context and alternatives.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the tool is safe. The description goes far beyond by detailing fan-out behavior, response structure (e.g., market_match_confidence, parent_event, news fields), safety mechanisms (low-confidence short-circuit, closed market handling), and resolution-rule parsing. This provides excellent transparency.

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

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

The description is lengthy but well-structured with clear sections (e.g., FAN-OUT EXAMPLES, RESPONSE SHAPES, RESOLVER CONTRACT). It front-loads the core purpose and uses CAPS headings. While verbose, the detail is justified for the tool's complexity, and it is 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?

For a complex tool with 3 parameters and no output schema, the description is highly complete. It explains response shapes, resolver contract, parent event extraction, news fields, safety, and edge cases, ensuring an agent can understand and use the tool correctly.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining how the 'depth' parameter affects fan-out (quick vs thorough) and provides input examples, enhancing understanding beyond the schema.

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

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

The description clearly states the tool's purpose: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies a specific verb (research, pull) and resource (Polymarket bet with Pipeworx data), and the extensive detail differentiates it from sibling tools like polymarket_edges.

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

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

The description provides explicit usage examples: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It clearly indicates when to use the tool, but does not explicitly mention when to avoid it or use alternatives, though sibling tools imply that.

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

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

Annotations already declare read-only, idempotent, non-destructive, and open-world. The description adds value by explaining data sources (SEC EDGAR/XBRL, FAERS, FDA), special handling of off-calendar fiscal years, and result ordering. 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 a single paragraph but packs essential information efficiently without redundancy. It front-loads the purpose and usage, though a bit dense. Slight improvement could be bullet points, but it remains accessible.

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

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

Given no output schema, the description adequately hints at return format (paired data + citation URIs). Along with rich parameter details and annotations, the agent has sufficient context to invoke and interpret results. Missing output structure details, but acceptable.

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

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

Schema coverage is 100%, but the description enriches understanding: for 'type=company' it specifies latest 10-K financials; for 'type=drug' it lists adverse-event counts, FDA approvals, and trial counts. It also clarifies behavior like sorted results and citation URIs, going well beyond the schema.

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

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

The description opens with example phrasings and clearly states the tool performs side-by-side comparison of 2–5 companies or drugs in a single parallel call. It distinguishes itself from sibling tools by explicitly recommending over sequential single-pack lookups and quantifying efficiency gains (replaces 8–15 lookups).

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

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

The description provides clear context on when to use (comparing entities, specific phrasings) and explicitly prefers over sequential lookups. It does not list specific alternatives or conditions to avoid, but the guidance is strong enough for an agent to decide.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is clear. The description adds details about return fields and the follow-up use of resource_id, which is useful but not extensive beyond the annotations.

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

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

The description is two sentences long, with the first sentence stating the core purpose and the second providing details on output and next steps. No unnecessary words, making it efficient and easy to parse.

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

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

Despite lacking an output schema, the description lists the returned fields (resource_id, name, description, category, update date) and hints at subsequent tool usage. It covers the essential information for a search tool, though pagination and error scenarios are not addressed.

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

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

Schema coverage is 100%, so each parameter has a description in the schema. The tool description does not add additional meaning beyond what is already in the schema, so the 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 searches the Texas Open Data catalog by keyword, which is a specific verb+resource. It also lists the returned fields, making its purpose unambiguous. Among sibling tools, none directly overlap with dataset searching, so it is well-distinguished.

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

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

The description implies a follow-up action (pass resource_id to query/metadata) but does not explicitly state when to use this tool versus alternatives or any exclusions. There is no guidance on optimal usage scenarios.

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

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

Discloses behavioral traits beyond annotations: account requirement, paid plan for certain depth, expected response time (15-60s), output structure (findings packet with gaps), and parallel execution across 4,552 tools. 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 with critical requirements (account, alternative tool). Every sentence adds value: account details, alternative, core functionality, usage guidance, limitations, and expected duration. No wasted words.

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

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

For a complex tool with 2 parameters and no output schema, the description adequately covers behavior, return structure, limitations, and context. References sibling tools and provides time estimate, making it complete for an agent to decide.

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

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

Schema coverage is 100%, so parameters are fully described in the schema. The description adds no new parameter information beyond what's in the schema (e.g., depth enum values already explained). Baseline 3 applies.

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

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

The description clearly states the tool performs grounded multi-source research across structured data sources, distinguishing it from sibling tools like ask_pipeworx for single lookups or breaking news. It specifies verb 'research' and resource '1160 structured data sources'.

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

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

Provides explicit when-to-use (broad/multi-part questions on structured data) and when-not-to-use (single lookups, breaking news) with named alternatives (ask_pipeworx). Also mentions account and plan requirements.

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 (all safe). The description adds value by stating that each result includes full input schemas with curated examples and is 'ready to call directly'. It also implies the response is a list of tools. 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 a single paragraph that efficiently conveys purpose, usage, and return format. It front-loads the action and domains, then adds response details. Every sentence is necessary 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?

Given the tool complexity (meta-discovery), annotations, and schema coverage, the description is largely complete. It explains what is returned (tools with names, descriptions, schemas) and when to use it. It could mention sorting by relevance, but overall it covers the key aspects.

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 examples of natural language queries and lists multiple aliases for the query parameter, which helps agents understand the flexibility. It also explains the limit parameter's default and maximum.

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 function: 'Find tools by describing the data or task.' It provides many example domains and explicitly distinguishes itself as the tool to call first when many tools are available. This differentiates it from sibling tools that perform specific tasks.

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

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

The description gives explicit usage context: 'Use when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST when you have many tools available...'. It does not explicitly state when not to use, but the guidance is clear enough. No alternative tools are mentioned, which is acceptable given the meta-nature.

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

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

Annotations already indicate read-only, idempotent, non-destructive. The description adds important behavioral details: parallel fan-out across sources, specific return structure, and a known potential failure (USPTO sunset). 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 somewhat long but each sentence adds value. It is front-loaded with examples and purpose, then details sources and outputs. A bit dense but justified by the tool's complexity.

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

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

No output schema, but the description thoroughly explains return values (CIK, company_name, filings, fundamentals, patents, news, LEI). It references sibling tool resolve_entity for names. The description is complete for a complex multi-source tool.

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

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

The input schema has 2 parameters with 100% coverage. The description adds context beyond the schema: how to pass ticker vs CIK, that names are not supported, and that only 'company' type is available.

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

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

The description explicitly states the tool provides a full cross-source profile of a US public company in one parallel call, with examples of user queries. It lists sources and return fields, distinguishing it from chaining individual lookups.

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

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

The description clearly indicates when to use this tool ('holistic view') and when to use an alternative ('use resolve_entity first' for names). It also notes that only ticker or CIK are supported, not names.

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 destructiveHint=true and idempotentHint=true. The description's 'Delete' is consistent but adds no new behavioral context beyond what annotations provide.

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

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

Two sentences front-load the action and usage, with no unnecessary words. Perfectly concise.

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

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

For a one-parameter tool with no output schema, the description covers purpose, usage, and parameter meaning adequately. 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% with a clear parameter description ('Memory key to delete'). The description's 'by key' adds minimal extra meaning, so baseline at 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?

Clearly states 'Delete a previously stored memory by key.' The verb 'delete' and resource 'memory' are specific, and the description distinguishes from sibling tools like 'remember' and 'recall' by mentioning them.

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 conditions: 'Use when context is stale, the task is done, or you want to clear sensitive data.' Also advises pairing with related tools.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds significant behavioral details: it fetches the page, extracts title/description/key links, emits the standard llms.txt markdown format, and produces a single text blob ready for site-root. 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 efficient: two sentences front-loading purpose and output, followed by a bullet list of use cases. 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 tool has only 2 parameters, no output schema, and good annotations, the description fully covers what the tool does, what output to expect (text blob), and includes usage scenarios. It is complete for an agent to select and invoke correctly.

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

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

Schema description coverage is 100% with clear descriptions for both parameters. The description adds value by stating max_links default (25) and maximum (50), and by providing an example URL format. This supplements the schema info beyond just restating it.

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 generates a production-ready llms.txt file for a URL. It specifies the verb 'generate', the resource 'llms.txt', and lists specific use cases (getting a client's site indexed, drafting for own project, auditing a competitor). It distinguishes well from sibling tools, none of which serve the same 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?

The description explicitly provides usage context: 'Useful for: getting a client's site indexed by AI, drafting llms.txt for your own project, or auditing how an AI crawler would see a competitor.' It implicitly suggests when to use but does not explicitly state when not to use or name alternatives, though no sibling tool appears to overlap.

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. Description adds value by specifying the exact fields returned, compensating for missing output schema. 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 concise sentences, front-loaded with purpose and return fields, no unnecessary words.

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

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

For a simple read-only list tool with one optional parameter and no output schema, description fully covers purpose, return shape, and usage hints. Annotations handle safety.

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 tool description does not mention the parameter, but schema is sufficient. Baseline score of 3 applies.

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

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

Clearly states it lists active subscriptions and enumerates return fields: id, type, params, created_at, etc. Distinguishes from sibling tools like subscribe and unsubscribe.

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

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

Explicitly advises use for reviewing current subscriptions before adding more or finding an ID to cancel, providing clear context for when to use this tool.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, which cover safety and idempotency. The description adds no additional behavioral context such as what happens with invalid resource_ids, caching behavior, or authentication requirements. It adds no value beyond annotations.

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

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

A single sentence that is front-loaded with the core action and resource, followed by specific metadata fields. Every word earns its place; no redundancy or fluff.

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

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

For a simple tool with one parameter and no output schema, the description is complete. It explains the input (resource_id) and the output (schema + metadata with specific fields). Combined with annotations, it provides enough context for an agent to use the tool correctly.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds value by providing an example resource_id value ("54pj-3dxy") and contextualizing it as a Texas Open Data dataset, making the parameter's format and purpose clearer than the schema alone.

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

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

The description clearly states the action (Get), the resource (Texas Open Data dataset's schema + metadata), and specifies the exact metadata components (columns, types, row count, category, last-updated). It distinguishes from siblings like 'datasets' and 'query' by its focus on schema and metadata retrieval.

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

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

The description implies usage when you have a resource_id and need schema/metadata, but it does not explicitly state when to use this tool vs alternatives, nor does it provide exclusions or when-not-to-use scenarios. It lacks explicit guidance on tool selection.

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

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

Annotations indicate destructiveHint=false, and the description adds behavioral traits: rate-limited to 5 per identifier per day, free, and not counted against tool-call quota. No contradictions with annotations. The description fully discloses constraints and side effects.

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 at four sentences, front-loaded with the core purpose, and every sentence provides necessary information without redundancy. It efficiently covers purpose, usage guidance, constraints, and output expectations.

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 simple nature (feedback submission with no output schema), the description is complete. It covers when to use, what to provide, constraints, and team process. No additional information is needed for effective 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%, and the description adds meaning beyond the schema, e.g., explaining the 'type' enum values in more detail and how to use the 'context' object. While the schema already describes the structure, the description clarifies usage, making it slightly above baseline.

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

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

The description clearly states the tool's purpose: sending feedback to the Pipeworx team about broken, missing, or needing functionality. It enumerates specific feedback types (bug, feature, data_gap, praise) and distinguishes itself from sibling tools by focusing on feedback rather than queries or research.

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

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

The description provides explicit guidance on when to use each feedback type and what to include (e.g., describe in terms of Pipeworx tools/packs, don't paste user prompts). It also mentions rate limits and that the tool is free and doesn't count against quota, enabling informed 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 indicate safe, read-only, idempotent behavior. Description adds valuable context: self-aggregating, no PII, caching details, and data source (CF analytics-engine). No contradiction.

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

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

Three sentences: first states output and window options, second lists use cases, third adds behavioral notes. Concise with no redundant words.

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

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

For a tool with one optional parameter and no output schema, the description covers purpose, usage, parameter semantics, and behavioral aspects fully. 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%. Description explains the single parameter 'window' with enum values, default, and semantic difference between short and long windows, adding beyond schema.

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

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

Clearly states it returns top tools, top packs, and total call volume over specified windows. Provides three explicit use cases, distinguishing it from siblings like ask_pipeworx or discover_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?

Lists three specific scenarios for use (discovery, confirmation, alignment). Lacks explicit when-not-to-use or alternatives, but context is clear and sufficient.

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

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

Beyond annotations (readOnlyHint, idempotentHint), the description adds extensive behavioral details: return format (opportunities[], partition_check, fill check), semantic anchor (Jaccard similarity threshold), partition filter (placeholder slugs), fill check with CLOB depth, and custom sizing advice. 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 lengthy but front-loaded with the main purpose and then details modes. Every sentence adds value, though slight trimming could improve conciseness. No wasted words.

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

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

No output schema, but the description thoroughly explains return structures, modes, filters, and edge cases. Covers all aspects needed for correct invocation and understanding of results.

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

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

Schema coverage is 100% but description adds rich semantics: for 'event', explains walking child markets and checks; for 'topic', cross-event scanning with similarity threshold. It adds meaning beyond the schema, addressing parameters comprehensively.

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

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

The description clearly states the tool finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes between three call modes (no args, event, topic) and specifies the resource (Polymarket), making it highly specific and distinguishable from siblings.

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

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

Explicitly says when to use each parameter: 'Call with NO args for a trending_scan', 'event (recommended for a specific market)', 'topic (for cross-event scanning)'. It provides recommendations and warns when not to trade (fill check). Clear and actionable guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds extensive behavioral context beyond annotations, including caching details, diagnostic outputs, edge correction formulas, Kelly sizing caps, slippage assumptions, and exclusion of Fed bets due to unreliable data. This fully informs the agent of the tool's behavior.

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

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

The description is lengthy and contains detailed explanations of model families, response structure, and parameter knobs. It is front-loaded with a clear summary, but the verbosity may dilute key points. It could be more concise by moving some technical details to separate documentation.

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 (9 parameters, no output schema, nested response), the description is comprehensive. It explains the return structure with by_segment, diagnostics, and caveats like Fed bets. Without an output schema, it provides sufficient detail for an agent to understand what the tool returns.

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

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

Schema coverage is 100% for all 9 parameters, so the baseline is 3. The description adds meaningful context: min_kelly skips small opportunities, min_edge_pp is net of slippage, slippage_pp explains zero fees but bid/ask, etc. This goes beyond the schema descriptions.

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

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

The description clearly states the tool scans top Polymarket markets to return opportunities where Pipeworx data disagrees with market price. It is built for discovering betting opportunities. However, it does not explicitly differentiate from sibling tools like polymarket_arbitrage or polymarket_edge_tracker, but the verb 'scan' and the focus on disagreements distinguishes it.

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 that agents can discover opportunities without paging through hundreds of markets and includes a section on 'TRADEABLE-EDGE KNOBS' that explains when to use filters like min_liquidity and max_spread_pp. However, it does not explicitly state when to use this tool versus alternatives like polymarket_arbitrage, and there is no comparison to sibling tools.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, etc., so the tool is safe. The description adds meaningful behavioral context: it uses daily snapshots, computes trends and decay, and explains gaps in data. No contradiction with annotations.

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

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

The description is well-structured with clear sections: purpose, response fields, limitations. It is front-loaded with the main question. However, it is somewhat verbose in detailing the response structure; could be slightly more concise.

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

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

Since there is no output schema, the description fully explains the return value format (tracked[], expired[], snapshot_dates[]) with field semantics. It also covers limitations (history depth, decay source). This is comprehensive for a tool with 2 optional params and no output schema.

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

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

Schema description coverage is 100%, so the schema already documents both parameters. The description adds minor context (days clamp 2-30, window family), but mostly repeats default values. Beyond the schema, it does not add significant new semantics.

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

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

The description explicitly states the tool provides 'edge persistence and decay telemetry' and answers a specific question about edge longevity. It clearly distinguishes from sibling tool 'polymarket_edges' by adding temporal analysis. The verb 'track' and resource 'edge persistence' 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 implies when to use the tool by framing it as answering 'how long has this edge existed and is it shrinking?' It also details limits (history depth, decay source). However, it does not explicitly state when not to use it or name alternatives beyond the implied sibling 'polymarket_edges'.

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 no destructive behavior. The description adds behavioral details such as walking the ladder, returning verdicts (clean|degraded|cannot_fill), and explaining that partial fills convert an arb into an unhedged position. This enriches the agent's understanding beyond annotations.

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

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

The description is well-structured with clear sections for single-market and basket modes. It is somewhat long but every sentence adds value. Front-loads purpose and usage. Minor verbosity keeps it from a perfect score.

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

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

Given the tool's complexity (two modes, no output schema), the description is highly complete. It explains inputs, modes, outputs (listing return fields), and critical behavioral nuances like forced directional risk and thin_legs. No major gaps for an agent to understand how to use it correctly.

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

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

Schema coverage is 100%, but the description adds significant meaning: it explains each parameter's role in both modes, clarifies defaults (size_usd default 1000, side default buy_yes or auto), and provides context like 'max spend on buys, target proceeds on sells' and 'settlement notional S (shares per leg)'. This goes well beyond the 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's purpose: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It details two modes (single-market and basket) and specifies that it should be used before acting on arbitrage signals or edge trades, distinguishing it from sibling tools.

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

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

Explicit usage guidance: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also warns about theoretical overround on thin books and partial basket fills creating unhedged directional positions, providing clear when-to-use and when-not-to-use 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?

Description significantly extends annotations by detailing compatibility_warning conditions, temporal alignment checks, skipped cross-type/subtype counters, and real-world behavior (e.g., venue pool differences, rarity of tradeable spreads). No contradiction with annotations (readOnly, openWorld, idempotent).

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?

Information is front-loaded with core concept, but the description is lengthy with inline list of shortcuts and extensive warnings. Could be more concise without losing critical details.

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

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

Despite no output schema, the description thoroughly explains response structure (leg-by-leg prices, top_spreads_pp, safety fields) and all edge cases (compatibility warnings, temporal alignment, skipped counters). Complete for a data retrieval tool.

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

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

Schema covers 100% of parameters, and description adds concrete values for topic shortcuts and explains override behavior with explicit tickers, providing meaningful context beyond schema descriptions.

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

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

The description clearly states the tool computes cross-venue spread between Kalshi and Polymarket for the same resolving question, with two modes and explicit response structure. It distinguishes from siblings like polymarket_arbitrage by its multi-venue focus.

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

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

Explicitly describes when to use topic shortcuts vs explicit tickers, and warns that most pre-mapped topics return compatibility_warning. However, it does not explicitly mention when to use alternative sibling tools like polymarket_arbitrage.

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

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

Annotations already declare readOnlyHint and idempotentHint, so the safety profile is covered. The description adds behavioral context: SoQL syntax (no leading $), pagination via limit/offset, and JSON return. No contradictions; description complements annotations well.

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

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

The description is a single, well-structured sentence that front-loads the core purpose (Socrata SoQL query) and then explains the filtering options and output. Every word earns its place; no fluff.

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

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

For a read-only query tool with a fully described schema and no output schema, the description adequately explains the input (SoQL clauses, limit/offset) and output (JSON rows). It misses minor details like default limit or error behavior, but overall is sufficient given the annotations and parameter coverage.

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

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

Schema description coverage is 100%, so the schema already documents all 7 parameters. The description adds marginal value by clarifying that SoQL clauses should be passed without the '$' prefix, but this is a minor addition. Baseline score 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 it runs a Socrata SoQL query against Texas Open Data datasets by resource_id, with explicit mention of SoQL clauses and return format (JSON). It distinguishes this tool from siblings that operate on different domains or data sources.

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

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

The description indicates when to use this tool: to query Texas Open Data with SoQL. It references resource_id from datasets (likely a sibling), but does not provide explicit when-not-to-use or alternatives. The context is clear enough for an agent to select it appropriately.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false; the description adds context about scoping (per identifier) and the listing behavior when key is omitted, providing a fuller picture of the tool's behavior beyond annotations.

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

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

Two well-structured sentences that front-load the action and purpose, with no extraneous information. Every sentence is value-adding.

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 optional parameter, no output schema, clear annotations), the description covers all necessary aspects: action, use cases, scoping, and relation to siblings. It is fully adequate for this 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% and the schema already describes the key parameter well (including the omission behavior). The description reinforces this but adds no additional semantic meaning; baseline 3 is appropriate.

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

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

The description clearly specifies the verb (retrieve/list) and resource (previously saved values/keys). It distinguishes from siblings by referencing 'remember' and 'forget' and explains the two modes of operation based on the presence of the key argument.

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

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

Provides explicit guidance on when to use: to look up previously stored context without re-deriving it. It also mentions scoping and pairing with remember/forget for full lifecycle management, helping the agent decide 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?

Description aligns with annotations (readOnlyHint, idempotentHint) and adds context on polling behavior, mark_read side effects, and alternative access method, surpassing what annotations alone 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?

Four concise sentences, each conveying essential information without redundancy. Front-loaded with purpose, then details, and ends with alternative access. No wasted words.

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

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

Given no output schema, the description compensates by enumerating output fields (source, citation_uri, raw payload). Covers filtering, mark_read behavior, and alternative endpoint. Complete for a read-only, idempotent tool with zero required parameters.

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, but the tool description adds value by explaining mark_read's effect and giving a concrete type example, enhancing 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?

Clearly states it pulls fired events from subscription feed, specifies returned fields (source, citation_uri, raw payload), and implicitly differentiates from sibling tools like list_subscriptions and recent_changes.

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 filtering examples (type, since), explains mark_read for polling, and mentions alternative REST endpoint. Lacks explicit comparison to siblings but offers sufficient guidance.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds significant behavioral context: parallel fan-out to multiple sources, GDELT→GNews fallback, USPTO soft-fail, structured return format with citation URIs. No contradictions with annotations.

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

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

The description is a single well-organized paragraph, front-loaded with example queries. It covers purpose, usage, parameters, sources, and alternatives without unnecessary verbosity. Some minor redundancy but overall efficient.

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

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

Given the 3 required parameters, lack of output schema, and rich annotations, the description provides everything an agent needs: purpose, when to use, parameter semantics, source behavior, and alternative tool reference. It is fully self-contained for correct invocation.

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

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

Schema coverage is 100% with descriptions for all parameters. The description adds extra meaning by explaining the 'since' parameter accepts ISO date or relative shorthand with examples, and confirms 'type' is limited to 'company'. This enriches the schema information.

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

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

The description clearly states the tool provides a 'change feed for a company in the last N days/weeks/months' with specific example queries and lists the data sources (SEC EDGAR, GDELT→GNews, USPTO). It also distinguishes from sibling 'entity_profile', making its purpose unambiguous.

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

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

The description explicitly tells when to use this tool (e.g., 'what's new with X') and when to use the sibling tool 'entity_profile' instead ('when you want the static profile regardless of window'). It also explains fallback behavior for GDELT→GNews and USPTO soft-fail, providing clear usage context.

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

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

Adds significant behavioral context beyond annotations: key-value pair scoped by identifier, persistence differences (authenticated vs anonymous, 24-hour TTL), and no contradiction with annotations (idempotentHint=true, destructiveHint=false).

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

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

Four well-structured sentences: purpose, usage guidance, technical scope, and paired tools. Front-loaded with core action, no wasted words.

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

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

For a simple two-parameter tool with no output schema, the description covers purpose, when to use, persistence behavior, and related tools. Adequate for effective agent decision-making.

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

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

Schema has 100% coverage with good descriptions (key examples, value as any text). Description reinforces but does not add meaningful new semantic detail beyond the schema.

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

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

Description uses specific verb 'save' and resource 'data', provides concrete examples (ticker, address, preference), and explicitly 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?

Clearly states when to use ('when you discover something worth carrying forward') and pairs with recall/forget for complementary operations, providing strong 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?

Annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false) already indicate safe, idempotent lookup. The description adds significant value by revealing internal cascading lookups, data sources (SEC EDGAR, RxNorm), and output format including citation URIs. No contradiction with annotations.

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

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

The description is well-structured starting with examples, then purpose, then type-specific details. Every sentence adds value, though slightly long. No wasted words, but could be tightened slightly for brevity.

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

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

Since no output schema exists, the description adequately covers return values (ticker+CIK+name+citation for company; RxCUI+ingredient+brand+citation for drug). It mentions internal cascading and auto-disambiguation. Lacks error handling or edge cases, but output coverage is sufficient.

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

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

Input schema has 100% coverage with clear enum for type and rough description for value. The description enhances meaning by specifying exact input formats (ticker, CIK, name for company; brand/generic for drug) and explaining auto-disambiguation for company names. Exceeds baseline 3 by adding practical usage details.

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

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

The description clearly states the tool resolves names to canonical IDs with specific verb+resource. It provides concrete examples ('What's the ticker for...') and lists supported types (company, drug) with output details. This distinguishes it from sibling tools like compare_entities or entity_profile which have 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 instructs 'Use FIRST whenever you have a name but need an ID,' providing strong when-to-use guidance. Examples cover multiple scenarios (ticker, CIK, RxCUI lookups). No alternatives mentioned, but the directive is clear and unambiguous.

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 no destructiveness. Description adds behavioral details: internal use of 'ai_visibility_check', ranked output with score/confidence/signal density, and conditional API key requirement. 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, each purposeful. Front-loaded with action and outcome. 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, but description covers return format. Parameter semantics are well explained. Could mention dependency on 'ai_visibility_check', but overall sufficient for an agent.

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

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

Schema has 100% coverage, so baseline is 3. Description adds valuable context: first entity is 'subject', model options and auth requirements, and context for disambiguation.

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

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

Description clearly states action ('Compare AI visibility across multiple entities side-by-side'), resource ('AI presence'), and distinguishes from sibling 'ai_visibility_check' which is a single-entity probe. Includes specific ranking and output details.

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 an explicit use case ('competitive AI-marketing audits') and a sample question. Does not explicitly contrast with other siblings like 'compare_entities', but the purpose is clear enough.

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?

Disclosed composite nature, fan-out to deps.dev and bundlephobia, partial failures degradation, timing for bundlephobia first measurement, and NPM-only limitation. Annotations already provide readOnlyHint and idempotentHint; description adds significant behavioral context without contradiction.

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

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

Dense but well-organized; starts with purpose, then details sources, output, and limitations. Could be slightly more structured (e.g., bullet points) but remains clear and efficient.

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

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

Given the tool's complexity (multi-source composite, partial failures, timing), the description covers inputs, behavior, output summary content, failure modes, and ecosystem scope. No output schema exists, but description adequately describes return values.

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

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

Schema coverage is 100% with descriptions for both parameters. Description adds value by clarifying scoped package acceptance (@types/node) and version default behavior, plus bundlephobia timing detail. Slightly above baseline given high schema coverage.

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

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

The description clearly states it's a composite check for npm packages covering license, advisories, version history, bundle size, and more. It uses a specific verb-resource combination and differentiates from siblings by being a one-call composite for dependency evaluation.

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 agent asks about safety/popularity/size/cost) and specifies NPM ecosystem only. Does not explicitly mention when not to use or list alternatives, but context is clear enough.

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 tool's safety profile is clear. The description adds valuable behavioral details: 'BGE-base-en embeddings + cosine over 500-char overlapping windows; cap is 200K chars (longer inputs are truncated and flagged).' 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 concise (about 4 sentences) and well-structured. It front-loads the core purpose, then provides usage guidance, technical details, and pairing advice. Every sentence adds value without 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 3 parameters, no output schema, and annotations covering safety, the description is fairly complete. It explains the return format (top-N passages with character offsets and similarity scores). However, it does not specify the exact output structure or mention pagination, which could be helpful but are not critical.

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

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

Schema coverage is 100%, so the schema already documents all parameters. The description adds extra context: for 'text' it notes max ~200K chars, for 'query' provides examples, and for 'limit' mentions default 5. This adds meaning beyond the schema, though not all parameters get equally detailed treatment.

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 'Semantic search INSIDE a fetched record' and explains the tool takes text and a query, returning passages with offsets and similarity scores. It distinguishes itself from sibling tools like ask_pipeworx_grounded by specifying it works on already-fetched text.

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

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

The description explicitly says 'Use when the record is too big to cram into the prompt' and recommends pairing with ask_pipeworx_grounded. It also provides an alternative use case (fetch with gateway, ground over passages), giving clear guidance on when to use this tool versus 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?

Discloses mutation behavior, idempotency, OAuth requirement, webhook secret one-time return, auto-disable after 10 failures, and SMS cap. 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 with purpose, then details. Slightly lengthy but each 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?

Thoroughly covers account, parameters, delivery options, and limitations. No output schema needed as return value is stated.

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

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

Adds significant value beyond schema with type-specific examples for params and delivery channels, including validation rules and limitations.

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

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

The description clearly states the tool creates proactive monitoring subscriptions to live-data event streams, specifies it returns a subscription ID, and distinguishes from siblings like list_subscriptions and unsubscribe.

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

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

Provides detailed guidance on account requirements (Pipeworx OAuth), supported subscription types with examples, and delivery channel options. Lacks explicit when-not-to-use scenarios but is otherwise comprehensive.

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 value by explaining what the tool returns (example questions with exact tool+argument shape) and that it draws from a live catalog. 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 informative but slightly long. It front-loads the core purpose and includes necessary details. A minor reduction in examples could improve conciseness, but overall it is 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?

For an onboarding tool with no output schema, the description fully covers what the tool does, how to use it, what it returns, and when to use it. It addresses the context of a new user needing guidance, making it complete.

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

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

Schema coverage is 100% with a single 'topic' parameter. The description adds meaningful context by listing the possible topic values (finance, pharma, etc.) and the behavior when omitted (full spread). 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?

The description clearly identifies the tool as an onboarding entry point that returns category-bucketed example questions, differentiating it from siblings like 'ask_pipeworx' and 'discover_tools'. It includes specific verbs ('return', 'use') and resources ('example questions', 'tool + argument shape').

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 this tool ('Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools'). It also explains how to focus with the 'topic' parameter. However, it does not provide explicit exclusions or alternatives for 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?

Description adds critical context beyond annotations: ownership enforcement and deactivation (not deletion), with reference to historical events via 'recent_alerts'. No contradiction with annotations (destructiveHint=false, idempotentHint=true).

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, focused sentences that are front-loaded with the main action and provide necessary details without extraneous information.

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

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

Covers the essential behavioral aspects (ownership, deactivation, historical events). Lacks mention of error handling for invalid ids or non-owned subscriptions, but still robust given the tool's simplicity.

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

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

Schema covers the single 'id' parameter with description; the description does not add additional semantic value beyond mentioning 'by id' and ownership, which is already implied.

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

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

The description clearly states the action 'Cancel a subscription by id' and specifies ownership enforcement and deactivation behavior, distinguishing it from sibling tools like 'subscribe' and 'list_subscriptions'.

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

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

Ownership enforcement is clearly stated, guiding that you can only cancel your own subscriptions. However, explicit when-not-to-use or alternative scenarios (e.g., permanent deletion) are not mentioned.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds value by detailing the return types (verdict, structured form, actual value, citation, delta) and the fact that it consolidates multiple steps. No contradictions.

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

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

The description is front-loaded with trigger phrases, is well-structured, and every sentence adds value. No wasted words.

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

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

Given the tool's simplicity (one parameter, no output schema), the description is complete: it explains scope, return format, and benefits, with annotations covering safety.

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

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

Schema coverage is 100% with a single parameter 'claim' described. The description reinforces natural-language examples and scope, adding context beyond the schema's brief description.

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

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

The description clearly states the tool's purpose: natural-language claim verification. It includes trigger phrases and distinguishes itself by noting it replaces 4-6 sequential calls, making it distinct from siblings.

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

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

Explicitly states when to use: 'whenever the agent needs to check whether something a user said is factually correct.' It also specifies the scope (company-financial claims) but does not explicitly mention when not to use, which would improve clarity.

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