Jersey Opendata

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

The description adds value beyond annotations by explaining the free default model, the requirement of an API key for Anthropic, and the return format (per-model scores, confidence, signals, raw_response). Annotations already indicate read-only and idempotent behavior, so no contradiction.

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

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

The description is four sentences, each serving a distinct purpose: defining core functionality, specifying default and optional behavior, summarizing return structure, and listing use cases. No wasted words; front-loaded with key action.

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

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

Despite lacking an output schema, the description clearly states the return structure (per-model {score, confidence, signals, raw_response} + combined view). It covers all parameters and provides practical use cases. It could be more complete with an example or error handling notes, but is sufficient for an experienced agent.

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

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

The input schema has 100% coverage, but the description enriches understanding: it explains the default model for the 'models' parameter, the pass-through nature of '_apiKey', and the disambiguation role of 'context'. This goes beyond the schema's bare descriptions.

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

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

The description explicitly states it probes LLMs for knowledge about an entity and returns a visibility score (0-100). It specifies default model and optional Anthropic integration, clearly distinguishing from sibling tools like ask_pipeworx or scan_competitor_ai_presence, which serve different purposes.

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

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

The description lists concrete use cases: AI-marketing audits, pre-launch brand checks, and competitive monitoring. It provides clear context for when to use the tool, but does not explicitly mention alternatives or when not to use it, which would further improve 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?

Even though annotations already declare readOnlyHint=true, idempotentHint=true, etc., the description adds valuable behavioral context: the tool routes the question to one of 5,564 tools across 1,462 sources, fills arguments, and returns structured answers with pipeworx:// citation URIs. It also notes 'one fast call' and that it works on every tier. 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 long but well-structured: starts with a bold recommendation, then lists capabilities, usage guidance, examples, and alternatives. It front-loads the most critical information (prefer over web search, default entry point). Minor verbosity in listing data sources could be trimmed, but overall every part justifies its presence.

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 (meta-routing to thousands of tools) and absence of an output schema, the description fully explains what the tool does, how it works internally, what it returns (structured answer with citation URIs), and when to use alternatives. It covers edge cases like breaking news and provides ample examples. No gaps remain.

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

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

Schema description coverage is 100% (all 6 parameters have descriptions in the schema). The description adds value by explaining the parameter accepts natural language questions and lists multiple aliases (query, q, prompt, text, input). It also provides example questions that illustrate how to phrase inputs, which goes beyond the schema's basic 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 answers factual questions about current/historical data using authoritative structured data with citations. It explicitly lists covered domains (SEC filings, FDA, economic stats, etc.) and distinguishes itself from web search and sibling tools like ask_pipeworx_grounded and deep_research. Examples solidify the 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 provides explicit usage guidance: 'PREFER OVER WEB SEARCH' and 'START HERE for most questions.' It gives clear alternatives: use ask_pipeworx_grounded for hallucination-resistant single answers and deep_research for broad/multi-part questions. It also addresses breaking-news cases, leaving no ambiguity about when to use this tool vs. siblings.

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

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

Annotations already convey read-only, idempotent, and non-destructive behavior. The description adds valuable context about the beta status, candidate routing experiments, and the fact that it has no fallback, which is more transparent than typical beta tool descriptions and goes beyond annotation basics.

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 four sentences long, with each sentence serving a distinct purpose: beta status, current state, usage guidance, and fallback clarification. It is front-loaded and well-structured, though slightly verbose for a tool that ultimately wraps a question-answering router.

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 lack of an output schema, the description references the 'same response shape' as ask_pipeworx, which is sufficient for agents familiar with the sibling. It covers experimental behavior, current candidate status, and usage context; the only missing piece is a concrete response format, but that is available via the stable tool.

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

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

Schema coverage is 100% with all six parameters documented as aliases for the 'question' field. The description provides no additional parameter semantics, but the schema itself fully explains the inputs, so the baseline score of 3 is appropriate.

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

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

The description clearly identifies this as a beta version of ask_pipeworx, a universal router with the same tools, arguments, and response shape. It distinguishes itself from the stable sibling by its beta status, though the core 'ask' functionality is implied rather than explicitly stated.

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

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

It explicitly states to use it exactly like ask_pipeworx when you want the newest routing, and explains that results are compared against the stable router. The current state (no candidate active) is noted, implying interchangeability, but it doesn't list exclusions or alternative tools beyond the stable version.

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

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

Annotations already indicate readOnly, openWorld, idempotent, and non-destructive. The description adds extensive behavioral detail: the structured response format (answer, evidence, confidence, source, fetched_at, refusal_reason), explicit refusal reasons, and the guarantee of not inventing facts. 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 well-structured: opening with core purpose, then behavior, then use cases, then trade-offs. Every sentence adds value. However, it is somewhat verbose (e.g., listing all refusal reasons in text). A slightly tighter version could achieve the same clarity with fewer words.

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

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

Given the tool's complexity (orchestration across 5,564 tools) and no output schema, the description does a thorough job explaining the output format, refusal reasons, and the cost trade-off. It lacks an explicit example of the output, but the structured response is clearly defined. For a high-stakes tool, the description is nearly 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 has 100% description coverage for all 6 parameters (all aliases). The description adds no extra meaning beyond what the schema already provides. It mentions the aliases again but does not add constraints like length limits or example formats. Baseline 3 is appropriate.

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

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

The description clearly states it is a 'Hallucination-resistant answer mode for high-stakes reads' and explains the mechanism: same routing as ask_pipeworx but extracts answer using only the tool result. It distinguishes itself from ask_pipeworx and other siblings by emphasizing factuality and structured output with evidence.

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

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

Explicitly specifies when to use: 'whenever an answer will be quoted, cited, or acted on' in high-stakes domains like financial verdicts, legal claims, medical lookups, and public statements. Also provides a clear alternative: 'prefer ask_pipeworx for casual lookups' due to the extra LLM call cost.

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

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

Annotations declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds extensive context: fan-out examples, response shapes, resolver contract, parent event extractor, news fields, safety mechanisms, and resolution-rule risk. 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 well-structured with clear sections and examples. It efficiently conveys complex information, though it could be slightly more concise.

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

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

Given the tool's complexity (fan-out, safety, edge cases, response shapes) and lack of output schema, the description covers return values, error states, and blocking conditions comprehensively. It is fully complete for an agent to use correctly.

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

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

Input schema coverage is 100%. Description explains the 'market' parameter thoroughly (slug, URL, question text) and provides examples. It also adds meaning for 'depth' and 'include_raw' beyond schema descriptions, justifying a score above baseline 3.

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

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

The description clearly states the verb 'research' and the resource 'Polymarket bet' with specific action 'pulling the relevant Pipeworx data'. It distinguishes this from sibling tools like polymarket_edges or polymarket_arbitrage by focusing on single-bet data aggregation.

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 cases are given: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z"'. It also describes when not to use via safety mechanisms (low-confidence matches, closed markets). However, it does not directly compare to sister 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?

The description adds significant detail beyond annotations: it explains exactly what data is pulled for each type (SEC EDGAR/XBRL for companies, FAERS/FDA/trials for drugs), mentions handling of off-calendar fiscal years, sorting by primary metric, and return format. This goes well beyond the readOnlyHint/idempotentHint 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 slightly dense but front-loaded with trigger phrases and core action. Each sentence contributes useful information without redundancy. Could be structured more, but it's effective.

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

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

Despite no output schema, the description covers return format (paired data + citation URIs) and specifics for each type. It is complete for a comparison tool with this complexity and 2 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?

Schema coverage is 100% with descriptions for both parameters. The description adds concrete examples (tickers/CIKs for company, names for drug) and constraints (min/max items), providing meaning 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 provides side-by-side comparison of 2–5 companies or drugs, with trigger phrases like 'compare X and Y'. It distinguishes between two types and the data each pulls, making it specific and distinct from siblings like entity_profile.

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

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

The description explicitly advises to 'ALWAYS PREFER over sequential single-pack lookups' and gives example queries. While it doesn't explicitly state when not to use it, the guidance is clear and context is provided.

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, destructiveHint=false, and idempotentHint=true. The description adds value by explaining the output structure (includes resources, specific fields to examine) and the relationship to datastore_query. 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?

Two efficient sentences: first states purpose, second provides actionable guidance on using the output. No unnecessary words, clearly front-loaded.

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

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

For a simple read-only tool with one parameter and no output schema, the description is complete. It explains what the tool returns and key fields to use, covering the user's likely information need. Annotations cover safety, and the description fills the gap left by the lack of output schema.

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

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

Only one parameter 'id' with schema description covering its type and format. The description reiterates 'by id or slug', which is consistent but adds minimal extra meaning beyond the schema. Baseline 3 due to 100% 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?

Description clearly states the tool retrieves a full Jersey dataset record by id or slug, including resources. It uses specific verbs (get/retrieve) and distinguishes from sibling tools like search_datasets and datastore_query by focusing on detailed single-record 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 provides some guidance on next steps (using datastore_query) but does not explicitly state when to use this tool over alternatives like search_datasets or datastore_query. The mention of 'read each resource's id, url, datastore_active flag' implies use for obtaining dataset details, but lacks explicit context on when not to use it.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds that the tool returns 'parsed records plus field definitions', giving insight into the output beyond basic read semantics.

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 that immediately convey purpose, prerequisite, and return value. No extraneous text; front-loaded with the key action.

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

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

Given the absence of an output schema, the description adequately explains the return format. The prerequisite condition is stated, and all parameters are covered by the schema. Handles a moderately complex tool (5 params, nested filters) 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%, so the description does not need to add much. It provides useful context for the resource_id parameter by referencing dataset_details, and the examples illustrate usage, but no parameter-specific details are added beyond what the schema offers.

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

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

Clearly states the tool reads actual table rows via CKAN datastore_search, specifying the resource type and a concrete example (population projections). Distinguishes from siblings like search_datasets by focusing on row-level data 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?

Explicitly states the prerequisite that datastore_active must be true and directs the user to obtain resource_id from dataset_details. Provides clear context for when to use the tool, though no direct comparison with alternatives is given.

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

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

Annotations already indicate readOnlyHint, openWorldHint, idempotentHint, non-destructive. The description greatly expands on this by detailing parallelism, response structure (findings with evidence, confidence, source, fetched_at, citations, gaps, contradictions for deeper depths), semantic excerpting of large records, hop field, citation_uri, and expected latency (15-60s, thorough up to 90s). No contradictions with annotations; rather, it enriches the behavioral profile.

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

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

The description is lengthy but every sentence provides essential information. It is well-structured: starting with account requirements, then core function, comparison with sibling, depth details, return format, and edge cases. Minor redundancy could be trimmed (e.g., 'ask_pipeworx' mentioned twice), but overall it earns its length without being wasteful.

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 there is no output schema, the description thoroughly explains the return format (findings packet with evidence, confidence, source, fetched_at, citations, gaps, contradictions, hop field, citation_uri). It also covers edge cases like large records being semantically excerpted, gaps when topics aren't in the catalog, and the behavior of each depth level. For a complex tool with only two parameters, this is highly complete and leaves no critical questions unanswered.

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% for both parameters, but the description adds significant meaning. For 'depth', it explains each enum value's behavior (quick=single hop, standard=gap recovery+contradictions, thorough=iterative chasing+contradictions+paid). For 'question', it clarifies that broad/multi-part questions are 'fine' because decomposition is the point. 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 performs 'grounded multi-source research across Pipeworx's 1462 STRUCTURED data sources' and explains it decomposes questions, routes to tools in parallel, and returns a findings packet. It explicitly distinguishes itself from ask_pipeworx (single lookup, news) and other siblings, making the unique purpose unmistakable.

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

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

Usage guidelines are explicit: best for 'broad/multi-part questions over structured data'; for a single lookup use ask_pipeworx; for breaking or current news prefer ask_pipeworx. The description also notes account requirements (free sign-in, paid for 'thorough') and suggests ask_pipeworx as a fallback if not signed in. Specific alternatives are named, providing clear when-to-use and when-not-to-use guidance.

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

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

The description aligns with annotations (readOnlyHint, idempotentHint, destructiveHint=false) and discloses all behavioral traits: it returns results that are 'ready to call directly, no second schema lookup needed.' There is no hidden behavior or contradiction.

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

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

The description is a single paragraph that front-loads the core purpose. Every sentence adds distinct information (scope, return type, usage advice). There is no redundancy or wasted words, making it highly efficient for an AI agent.

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

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

The description fully covers the tool's role as a discovery mechanism: it explains what it returns (top-N tools with schemas and examples), when to use it (first when browsing many tools), and how input works (natural language query with aliases). No gaps remain for an agent 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% with descriptions for all parameters. The description adds value by explaining that query accepts aliases and providing concrete examples (e.g., 'analyze housing market trends'). This goes beyond the schema by clarifying usage context.

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

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

The description clearly states the tool's purpose: 'Find tools by describing the data or task.' It specifies the return value (top-N tools with names, descriptions, and full schemas) and distinguishes from sibling search tools by emphasizing that this is a meta-discovery tool for browsing the option set.

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

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

The description explicitly advises to 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This provides clear guidance on when to use it, though it does not explicitly list when not to use it or compare with specific sibling tools like search_datasets.

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 significant behavioral context: it fans out across multiple sources, details specific return fields (cik, filings with URIs, fundamentals sorted by period, patents with sunset warning, news via fallback, LEI), and notes soft-failures. 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 relatively long but well-structured with examples, a bullet-like list of return fields, and a clear warning about limitations. It is front-loaded with purpose and examples. Some internal details could be trimmed (e.g., specific sunset date for patents), but overall it balances completeness with usability.

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

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

Given no output schema, the description fully documents what is returned (cik, filings up to 5 with URIs, fundamentals, patents, news, LEI). It also covers limitations (no names, patent sunset) and fallback mechanisms. The tool has only 2 required params, and the description provides all necessary context 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?

Both parameters have schema descriptions (100% coverage), so baseline is 3. The description adds value by providing concrete examples ('AAPL', '0000320193'), reiterating that names are not supported, and specifying the format for the value parameter. This clarity exceeds the baseline.

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

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

The description clearly states the tool provides a 'full cross-source profile of a US public company in ONE parallel call' with specific examples like 'brief me on Tesla' and lists exactly what data is returned. It distinguishes from siblings by emphasizing it is preferred over chaining single-source lookups and by noting that names are not supported (use resolve_entity instead).

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

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

Explicitly states 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' Also instructs to use resolve_entity if only a name is available, and lists supported inputs (ticker or CIK). Provides clear context for when to use and when not.

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 destructiveHint=true and idempotentHint=true. Description adds context about clearing sensitive data, but doesn't clarify behavior for non-existent keys or edge cases. Minor gap beyond annotation coverage.

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

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

Two concise sentences with no wasted words. Efficiently conveys purpose, usage guidance, and sibling relationship.

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 delete tool with one required parameter and no output schema, description covers purpose, usage, and sibling context completely. No gaps.

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

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

Schema coverage is 100% and schema already describes the 'key' parameter as 'Memory key to delete'. Description adds no further semantics or format details beyond schema.

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

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

Description explicitly states 'Delete a previously stored memory by key.' Clear verb+resource. Distinguishes from sibling tools 'remember' and 'recall' by being the deletion counterpart.

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 conditions: 'when context is stale, the task is done, or you want to clear sensitive data the agent saved earlier.' Also pairs with 'remember and recall', guiding appropriate 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 declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds details: fetches page, extracts title/description/key links, emits standard markdown. No contradictions.

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

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

Two sentences plus a list of use cases. Front-loaded with purpose, followed by behavior and usage. No redundant or missing 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 2 parameters, no output schema, and annotations, the description fully explains the tool's operation, output format, and use cases. Adequate 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 covers both parameters fully (100% coverage). Description adds context (e.g., default and max for max_links) and behavioral context (fetches page, extracts data), but schema descriptions are already clear.

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

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

Clearly states 'Generate a production-ready llms.txt file for any URL', specifying the verb and resource. Distinguishes from sibling tools like ai_visibility_check and scan_competitor_ai_presence which serve different purposes.

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

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

Lists explicit use cases: getting a client's site indexed, drafting for own project, auditing competitor. Does not include exclusions or when-not-to-use, but the use cases are comprehensive given the tool's specificity.

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, covering the safety profile. The description adds domain-specific context (e.g., examples of groups, CKAN reference) without contradicting annotations. No additional behavioral details are needed beyond annotations.

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

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

The description is a single, efficient sentence that includes the action, resource, platform, examples, and context (CKAN). No wasted words; front-loaded with key information.

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

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

For a simple listing tool with one optional parameter and no output schema, the description provides sufficient context: it explains what groups are (thematic categories), gives concrete examples, and mentions the underlying CKAN API. No gaps in understanding for the agent.

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

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

The single parameter 'limit' is fully described in the input schema (max 1000, default 100). The description does not add any additional meaning beyond the schema, which already provides complete coverage. Baseline score of 3 is appropriate.

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

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

The description uses the verb 'List' to clearly indicate the action, specifies the resource as 'thematic groups/categories', and ties it to the specific platform opendata.gov.je with concrete examples like 'Economy and business'. This clearly distinguishes it from sibling tools like list_organizations.

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 an example usage (limit=100) and notes it is a CKAN group_list, implying its use for listing groups. However, it does not explicitly state when to use this tool versus alternatives (e.g., search_datasets, list_organizations) or provide any when-not-to-use guidance.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds no behavioral traits beyond confirming it lists from a specific endpoint. It is consistent but adds no extra useful behavioral context.

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

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

The description is a single, concise sentence of 21 words, front-loaded with the purpose and includes a specific example. 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 list tool with one optional parameter, the description covers the purpose, domain, and endpoint. Annotations cover safety traits. No output schema is needed for such a straightforward tool.

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

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

Schema coverage is 100% with the 'limit' parameter fully described (max orgs, range, default). The description does not add any additional meaning or context to the parameter beyond what the schema provides.

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

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

The description clearly states the tool lists publishing organizations (Jersey government departments/agencies) from opendata.gov.je, using CKAN organization_list. It distinguishes from siblings like list_groups or search_datasets by specifying the domain and platform.

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 through context (Jersey government) but does not explicitly state when to use this tool versus alternatives like list_groups or search_datasets. No exclusions or guidance on prerequisites.

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

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

Annotations cover read-only, idempotent, open-world, and non-destructive traits. The description adds that it returns specific fields and is scoped to the caller, plus hints at the id's role in cancellation. No contradictions. Adds useful context beyond annotations.

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

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

Two sentences: first states purpose, second adds usage guidance and return fields. Every sentence adds value, with no extraneous text. Front-loaded and efficient.

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

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

For a simple list tool with one optional parameter and annotations covering safety, the description provides sufficient information: what it returns, when to use it, and the default scope. No output schema needed as fields are enumerated in description.

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. The tool description indirectly references the parameter by mentioning 'active', but does not add meaning beyond the schema. Baseline 3 is appropriate.

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

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

The description uses a specific verb ('List'), names the resource ('subscriptions'), and clarifies scope ('caller's active'), distinguishing it from sibling tools like 'subscribe' and 'unsubscribe'. The return fields are listed, making the output clear.

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

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

Explicitly states when to use the tool: 'review what you're monitoring before adding more or to find an id to cancel'. This directly relates to sibling tools 'subscribe' and 'unsubscribe', providing 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 are all false/neutral, so the description carries the full behavioral burden. It reveals the claim_token flow (filing without an account returns a token that can be reused to check status), a rate limit (5 per identifier per day), the free status, and that the team reads digests daily. These details go well beyond annotation metadata and set clear expectations.

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

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

Front-loaded with purpose, followed by usage triggers, exclusions, message guidance, token mechanics, and quota. The length is appropriate for the tool's complexity, though a few phrases (e.g., the claim_token sentence) repeat schema text. Each sentence earns its place, but trimming redundancy would make it tighter.

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 no output schema, the description fully explains the interaction model: when to file, what to say, how to claim/lookup a response, and operational constraints (rate limit, free, roadmap impact). It also addresses edge cases like 'not sure? Pipeworx tool names are the ones this connection lists.' This is complete for the tool's complexity.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds useful context beyond the schema, such as 'don't paste the end-user's prompt' and clarifies how claim_token is used in a call. It also ties the context object to 'Pipeworx tools/packs,' which helps with message/context formatting. Slight redundancy with schema, but enough added value for a 4.

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

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

The description opens with a clear action statement: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It then enumerates concrete use cases (bug, feature/data_gap, praise), making the tool's purpose unmistakable and distinguishing it from sibling tools that query data or answer questions.

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

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

Explicitly states when to use the tool ('Use when a tool returns wrong/stale data...') and when not to ('ONLY for tools served by this Pipeworx connection... if the tool came from a different MCP server... file it with that server instead'). It even names the alternative action, providing strong usage guidance.

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

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

Beyond annotations (readOnly, idempotent), the description adds behavioral context: data source (CF analytics-engine), no PII, cached 5min-1h. Does not contradict annotations.

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

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

Description is a single paragraph that front-loads the main purpose. It is informative but not overly concise; every sentence adds value, but could be slightly more streamlined.

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

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

For a simple tool with one optional parameter and no output schema, the description covers purpose, usage, parameter semantics, and behavioral aspects sufficiently.

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 already covers parameter 'window' with enum and description. Description adds nuance (shorter windows for hot topics, longer for steady-state demand), adding value beyond schema.

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

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

The description clearly states the tool returns top tools, top packs, and total call volume over a recent window, using specific verbs and resource. It distinguishes itself from siblings by focusing on aggregated trending data from other AI agents.

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

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

The description provides explicit use cases (discovering hot data sources, confirming canonical choice, aligning use case) and explains window duration differences (short vs long windows). It lacks explicit when-not-to-use guidance but is highly useful.

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 extensive behavioral details: walks child markets, checks date-axis/threshold-axis ordering, partition_check with deviation >3pp emitting BUY/SELL EVERY LEG signal, semantic anchor with Jaccard similarity threshold, partition filter for placeholder slugs, fill check distinguishing theoretical vs realizable edge, and reference to polymarket_fill_risk. No contradiction with annotations.

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

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

The description is long due to the tool's complexity, but well-structured: first sentence states overall purpose, then paragraphs for each mode, followed by semantic anchor, partition filter, fill check. Every sentence adds necessary detail. Could be slightly more concise, but the length is justified.

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 no output schema, the description covers modes, parameters, behavioral edge cases (similarity threshold, placeholder filter), fill check (realizable_edge_pp ≤0 means don't trade), and response structure (opportunities[] with fields, partition_check in event mode). Also references polymarket_fill_risk for custom sizing. Very 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 description coverage is 100%, but the description adds significant value: explains that event slug can be a full URL, defines 'topic' as a seed question that triggers cross-event scanning, and details behavior for no args (trending_scan of top ~200 markets). It enriches the parameters with context and recommended usage.

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

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

The description clearly states the tool's purpose: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It specifies the verb (find), resource (arbitrage opportunities on Polymarket), and method (monotonicity violations + partition-sum checks). It distinguishes between three modes (no args, event, topic) and differentiates it from sibling tools like polymarket_edges, polymarket_fill_risk, etc.

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 mode: 'Call with NO args for a trending_scan...', 'event (recommended for a specific market)...', 'topic (for cross-event scanning)...'. It explains advantages like 'Cross-event mode catches ... patterns that single-event misses.' It doesn't explicitly state when not to use the tool or mention alternatives, but sibling tools offer context. Overall, it's very helpful.

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

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

The description extensively details behavioral traits beyond annotations: model families (MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, CONCENTRATED_LONGSHOT), response structure (by_segment, diagnostics), tradeable-edge knobs, caching (1h), and the 24h-move warning. This far exceeds the readOnlyHint, openWorldHint, and idempotentHint annotations.

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

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

The description is front-loaded with the core purpose and structured with subheadings, but it is verbose and dense, potentially overwhelming an AI agent. It could be more concise while maintaining comprehensiveness.

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 (3 segments, 9 parameters, no output schema), the description is remarkably complete. It explains response structure (by_segment, diagnostics), each opportunity's fields, tradeable-edge knobs, and caching behavior. This fully equips an AI agent to use the tool effectively.

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

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

The input schema provides 100% description coverage for all 9 parameters, so baseline is 3. The description adds no new meaning beyond the schema; it mentions knobs but in a usage context, not parameter semantics. Therefore, the score remains at 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: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It uses specific verb (scan, return) and resource (Polymarket markets), and distinguishes from siblings by specifying its unique value proposition ('what should I bet on today').

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

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

The description implies usage for discovering betting opportunities but does not explicitly state when not to use or contrast with siblings like polymarket_arbitrage or polymarket_edge_tracker. It mentions 'without paging hundreds of markets' but lacks direct alternatives or exclusions.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds substantial behavioral context: explains response structure (tracked, expired, snapshot_dates), computation of decay from daily closes (not intraday), limits like 60-day TTL, and data gaps. No contradictions.

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

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

The description is well-structured: opening purpose, then args, then response details with clear field explanations. It is somewhat verbose but each sentence provides value. Front-loaded with the key insight. Could be slightly more concise, but effective.

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

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

Given no output schema, the description thoroughly covers all return values (tracked, expired, snapshot_dates with their subfields). It explains limitations (60-day TTL, start of snapshotting, daily closes). The tool is complex, and the description leaves no major 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 clear descriptions for both parameters. The description adds context: default values (14, 1wk), acceptable range for days (clamp 2-30), and example values for window (24hr, 1mo). This adds meaningful usage context beyond the schema.

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

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

The description clearly states the tool provides 'edge persistence and decay telemetry' and answers 'how long has this edge existed and is it shrinking?'. It distinguishes from sibling tools like polymarket_edges by focusing on historical time-series and decay, using a specific verb ('tracker') and resource (edges over time).

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 (when interested in edge persistence/decay rather than current edges) and contrasts a fresh vs aged edge, but does not explicitly state when not to use or provide direct alternatives among siblings. Context from sibling list helps, but slightly less explicit guidance.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds rich behavioral context: walks the order book ladder, returns specific fields (top_of_book, vwap_fill_price, slippage_pp, etc.), explains basket mode details, and warns about thin books and stranded positions. No contradiction with annotations.

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

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

The description is long but efficiently structured with mode-specific sections and clear formatting (CAPS, line breaks). Every sentence adds value—no redundancy or fluff. It is front-loaded with the core purpose.

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

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

For a complex tool with 4 parameters, no output schema, but detailed explanation of return fields in the description, it is highly complete. Covers both modes, return values, warnings, and usage context extensively.

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

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

Schema description coverage is 100%, but the description adds significant meaning beyond schema: size_usd interpretation differs by mode (max spend vs target proceeds vs settlement notional), side default logic for basket mode, and clamp range for size_usd. Each parameter gets context-specific elaboration.

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

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

The description states a specific verb-resource combination: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It clearly distinguishes between single-market and basket modes, differentiating it from sibling tools like polymarket_arbitrage and polymarket_edges.

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

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

Explicitly says 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It explains when not to use and warns about partial basket fills converting arb into unhedged directional position.

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

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

Annotations indicate read-only, idempotent, open-world. The description adds crucial behavioral context: compatibility warnings for non-equivalent bet shapes, temporal alignment, and skipped comparison counters. 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 thorough but lengthy. It is well-structured with sections (modes, response, safety fields). Could be slightly more concise, but the complexity warrants detail.

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

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

Given no output schema, the description covers response structure (prices, spreads, safety fields). It addresses temporal alignment and compatibility comprehensively, leaving minimal gaps 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 coverage is 100% with clear descriptions. The description adds meaning by explaining the two usage modes and providing examples, though some param details are redundant.

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

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

The description clearly states the tool computes cross-venue spread between Kalshi and Polymarket for the same resolving question. It distinguishes from siblings like polymarket_arbitrage by focusing on cross-venue comparison.

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

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

The description explicitly outlines two modes (topic and explicit) and explains when compatibility_warning indicates the spread is not meaningful. However, it doesn't directly compare to alternatives 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 indicate readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds value by explaining the list-all mode, scoping to identifier, and the pair relationship with remember/forget. No contradictions.

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

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

The description is three sentences with no extraneous words. It is front-loaded with the main action and 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?

There is no output schema, so the description should hint at return format. It implies returning a value or list of keys, but does not specify structure. Given the simplicity and read-only nature, it is reasonably 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 'key' parameter. The description adds the crucial behavior: omitting key lists all keys. It also gives examples like 'user_research_topic'. This enriches meaning beyond 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 tool retrieves a value saved via remember or lists all keys when key is omitted. It specifies the verb 'retrieve' and the resource 'value previously saved', and distinguishes from sibling tools like remember and forget.

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

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

The description provides clear usage context: looking up stored context (ticker, address, notes) without re-deriving it. It mentions scoping by identifier and pairing with remember/forget. While it doesn't explicitly state when not to use it, the simplicity and sibling names make the guidance 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?

The description describes mark_read:true causing a state change (flagging events read), which contradicts the annotation readOnlyHint=true. While the description is transparent about this behavior, the rule requires a score of 1 when a contradiction exists.

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 (3 sentences), front-loaded with the main action, and each sentence adds value: purpose, return fields + filtering, and behavior/alternative. 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 5 optional parameters, no output schema, and rich annotations, the description covers return fields, filtering, mark_read behavior, and an alternative method. It does not explain pagination or error handling, but is sufficient for typical use.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds context for type, since, and mark_read (e.g., 'Flag the returned events read'), but does not address the unread_only parameter. The schema already describes all parameters, so the description adds marginal value.

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

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

The description clearly states it 'Pull fired events from your subscription feed', specifying the verb (pull), resource (subscription feed), and what is returned (source, citation_uri, payload). It differentiates from siblings by being the dedicated tool for recent alerts, with no other sibling tool serving this 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 mentions that 'Polls work fine' and provides an alternative REST endpoint for scripts and dashboards, giving clear context on when to use this tool versus the REST API. However, it does not explicitly state when not to use this tool compared 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, openWorldHint, idempotentHint, and destructiveHint. The description adds significant behavioral context: it fans out to multiple external APIs, explains fallback logic (GDELT→GNews), notes USPTO soft-fail status, and describes the return structure (grouped changes, total_changes, 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 dense paragraph that front-loads example queries and purpose. Every sentence adds value, but it could be better structured (e.g., bullet points for sources). Still concise given the amount of information conveyed.

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

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

Given the tool's complexity (multiple data sources, fallback logic, parameter types, return structure) and no output schema, the description covers everything needed: sources, fallback, return format with citation URIs, parameter guidance, and alternative tool reference.

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 practical guidance: for `since`, it clarifies relative shorthand and recommends '30d' or '1m'; for `value`, it gives examples (ticker or CIK). This extra context raises the score to 4.

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

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

The description starts with clear example queries and states 'change feed for a company in the last N days/weeks/months in ONE parallel call.' It explicitly lists data sources (SEC EDGAR, GDELT→GNews, USPTO) and distinguishes from sibling entity_profile, making the purpose specific and unambiguous.

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

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

The description provides explicit when-to-use scenarios ('What's new with X', 'latest on Y') and when-not-to-use ('Use entity_profile instead when you want the static profile'). It also explains fallback behavior (GDELT→GNews) and parameter recommendations ('Use '30d' or '1m' for typical monitoring').

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

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

Annotations already indicate idempotent and non-destructive. Description adds valuable context about scoping by user identifier and persistence differences (permanent for authenticated, 24h for anonymous).

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

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

Four sentences, each serving a clear purpose: purpose, usage, behavior, pairing. No wasted words.

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

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

For a simple tool with two string params and no output schema, the description covers all needed aspects: purpose, when to use, behavior, and integration with sibling tools.

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

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

Schema coverage is 100%, so description doesn't need to add much. It provides usage examples but no additional syntactic detail beyond schema.

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

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

Description clearly states the tool saves data for reuse across conversations/sessions, with specific examples like 'resolved ticker' and 'user preference'. It distinguishes from sibling tools (recall, forget) by mentioning pairing.

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

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

Explicitly says when to use ('when you discover something worth carrying forward') and references alternatives ('Pair with recall to retrieve later, forget to delete').

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 mark it read-only, idempotent, non-destructive, and open-world. The description adds uncovers details: identifiers are source-labeled, unresolved ones appear explicitly, enrichment degrades gracefully, and internal cascading happens. This goes well beyond the annotations and tells the agent what to expect in return data.

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 packed with value but very long, front-loading an extensive list of example queries and then a dense block of type-specific details. It is well-structured but could be trimmed without losing clarity; it's more thorough than 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?

The tool has two entity types with multiple identifier sources and edge cases (ISIN, non-US issuers, degradation). The description covers input formats, output semantics, failure behavior, and internal cascading, making it nearly self-sufficient for a new agent. The absence of an output schema is compensated by the description's detail.

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

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

With 100% schema coverage of the two parameters, the baseline is 3. The description elevates this by clarifying accepted formats for `value` (ticker, CIK, ISIN, name for company; brand/generic for drug) and the ISIN-to-legal-entity mapping, which adds meaning beyond the schema's terse 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 opens with concrete user queries and states the tool resolves names to canonical identifiers other tools need. It clearly covers two entity types and distinguishes this from sibling tools by positioning it as a first-stop lookup, 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?

The description explicitly says 'Use FIRST whenever you have a name but need an ID', giving a clear directive for when to choose this tool. It also notes that one call replaces 2-3 manual lookups, framing its value. It doesn't name alternatives but the instruction is decisive 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 indicate readOnly, idempotent, not destructive; description adds behavioral details: probes each entity with ai_visibility_check, ranks, surfaces most/least recognized. 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?

Two sentences, front-loaded with core function, second sentence adds context and return info. No waste.

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

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

No output schema, but description specifies return: ranked list with score, confidence, signal density. Covers purpose, process, and output adequately.

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

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

Schema description coverage is 100%, so description adds little beyond schema. It clarifies entities' first entry as subject, which is mild added value.

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

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

The description clearly states the tool compares AI visibility across multiple entities, specifying verb, resource, and scope. It distinguishes from siblings like ai_visibility_check (single entity) and compare_entities (general).

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 context (competitive AI-marketing audits) and implies when to use (multi-entity comparison) versus alternatives. It does not explicitly state when not to use but 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, destructiveHint=false. The description adds significant behavioral details: fans out across deps.dev and bundlephobia, partial failures degrade gracefully, bundlephobia timeout (5-30s), and lists exact return fields. No contradictions with annotations.

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

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

The description is one dense paragraph, but every sentence adds value (purpose, usage, ecosystem scope, partial failure behavior). It is front-loaded with the main purpose. Slightly long but efficiently packed.

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 (composite check, external services, partial failures, no output schema), the description is fully comprehensive. It explains return fields, sources_failed, links, and alternative versions, leaving no critical gaps.

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

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

Schema coverage is 100% (both package and version described). The description adds minor context (scoped packages accepted, version defaults to latest) but largely repeats schema. With high coverage, 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 opens with a clear verb phrase ('Composite should I add this npm package to my project check in ONE call') specifying the resource (npm package) and the action (composite safety/popularity/size check). It is distinct from sibling tools, none of which scan npm packages.

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

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

Explicitly states when to use: 'Use whenever an agent asks 'is X safe / popular / small' or 'what does adding lodash cost me''. Also clarifies limitations: 'NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly', providing a clear alternative.

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 as true/false, covering the safety profile. The description adds minimal behavioral context by stating it returns matching datasets with specific fields. It does not contradict annotations.

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

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

Two sentences with zero wasted words. The first sentence states core functionality and source; the second adds geographic and publisher context. It is front-loaded and efficient.

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

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

Given the tool has 5 parameters and no output schema, the description covers key aspects: what it searches, what it returns (titles, descriptions, resources), and the source. It lacks explicit mention of pagination (start, rows) or default behavior, but these are partially covered in the schema. Overall, it is largely complete for a search tool.

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

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

Schema description coverage is 100%; all five parameters have clear descriptions in the schema. The description itself adds no additional details about parameters beyond summarizing the return. Baseline score of 3 is appropriate as the schema does the heavy lifting.

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

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

The description clearly states the verb 'Search' and the resource 'Government of Jersey open-data catalogue', specifying the source (opendata.gov.je, CKAN package_search). It provides context about Jersey and Statistics Jersey. However, it does not explicitly differentiate from sibling tools like dataset_details or search_within, which could cause confusion in selection.

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

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

The description implies usage for searching that specific catalogue and notes the return format (titles/descriptions/resources). It lacks explicit guidance on when not to use this tool or mention alternatives such as dataset_details for a single dataset or search_within for internal searches. The context is implicit but not fully directive.

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

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

Describes internal mechanics (BGE-base-en embeddings, cosine similarity, 500-char overlapping windows), specifies a 200K char limit with truncation flagging, and explains output format (passages with offsets and scores), adding value beyond annotations which only declare readOnly, idempotent, etc.

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

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

Concise yet information-dense; each sentence adds value, front-loaded with the core purpose, and no wasted words.

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

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

Complete for a tool with 3 params and no output schema; covers what it returns, limitations, and behavioral details, making it self-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?

Input schema has 100% coverage with descriptions; the description adds further context such as max chars for 'text' and example queries for 'query', enhancing parameter understanding.

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

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

Description clearly states it performs semantic search inside a fetched record, providing concrete examples (SEC 10-K, article) and distinguishing it from siblings by mentioning pairing with ask_pipeworx_grounded.

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

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

Explicitly says when to use (when record is too large for the prompt) and provides guidance on pairing with another tool, making it easy for the 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?

The description adds extensive behavioral details beyond annotations: requires OAuth, explains delivery channels (always-on feed, optional email/sms/webhook) with constraints (SMS verification, 10/day cap, webhook signing, auto-disable). All annotations (readOnlyHint=false, openWorldHint=true, idempotentHint=true, destructiveHint=false) are consistent with the description.

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

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

The description is well-structured with a clear front-loaded purpose statement and organized details for types and delivery. While lengthy, every sentence adds value; minor redundancy could be trimmed but overall efficient.

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

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

Given no output schema, the description mentions the return of subscription ID and covers all necessary context: account requirements, supported types with params, delivery options with constraints. The agent has enough information to invoke the tool correctly.

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

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

Schema coverage is 100%, and the description enriches parameters with type-specific examples (e.g., sec_8k items, polymarket_edge topic) and delivery channel details (webhook signing, SMS verification). This adds meaning beyond the schema's basic descriptions.

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

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

The description clearly states the tool creates a proactive monitoring subscription to a live-data event stream and returns the new subscription ID. It distinguishes itself from siblings like list_subscriptions and unsubscribe by specifying the creation action and the types of subscriptions.

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

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

The description explicitly mentions requirements (Pipeworx OAuth account, anonymous/BYO cannot persist) and provides supported types with examples. It lacks explicit 'when not to use' guidance or direct comparison with alternatives like polling via recent_alerts, but the context is clear enough for an agent to decide.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, indicating safe, read-only, and non-destructive behavior. The description adds value by explaining the output format (example questions with tool calls) and that it draws from a live catalog. 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 is informative but slightly dense. It uses slashes for alternative phrasings and lists categories, but could be more structured for easier scanning.

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 one optional parameter and no output schema, the description is complete. It explains the use case, input, output, and categories, leaving no gaps for the agent.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning by explaining the parameter 'topic' is optional, lists specific focus areas, and states omitting gives a cross-category spread, going beyond the schema's description.

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

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

The description clearly states the tool returns category-bucketed example questions and the exact tool + argument shape that answers them, positioning it as an onboarding entry point. The title 'What Can I Ask Pipeworx?' reinforces this purpose, and it distinguishes from siblings by being the first tool to use when unsure of capabilities.

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 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 specifies when to pass a topic vs. no arguments. It does not explicitly state when not to use, but the context is clear.

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

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

Beyond annotations (readOnlyHint=false, destructiveHint=false), description clarifies that the row is deactivated, not deleted, and historical events remain available. This adds valuable behavioral detail without contradicting annotations.

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

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

Two sentences, front-loaded with purpose, no wasted words. Efficiently conveys all key information.

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

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

For a simple tool with one parameter and no output schema, the description covers purpose, ownership constraint, and behavioral effect (deactivation vs deletion). Sufficient for an agent to use correctly.

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

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

Schema has 100% coverage. Description adds context that the id is 'returned by subscribe,' linking to the source, which aids understanding. No additional syntax details needed.

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?

Explicitly states 'Cancel a subscription by id,' clearly indicating action and resource. Distinguishes from sibling tools like subscribe and list_subscriptions.

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

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

States ownership enforcement ('you can only cancel your own subscriptions'), providing clear context for when the tool is usable. Does not explicitly mention alternatives or when not to use, but the constraint is informative.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, and the description adds meaningful behavioral detail: it differentiates between could_not_verify (verification failure) and unsupported (no source), which is critical for callers to interpret results correctly. It also discloses the fast-path vs grounded routing and the output verdict set, which are not present in 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 long but information-dense: it covers purpose, usage, routing, output, and caller warnings in a logical order. The opening phrasings are slightly redundant but serve as NL triggers, and the 'IMPORTANT' callout helps prevent misuse. It is structured well but could be trimmed slightly without losing value, so a 4.

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?

This tool has no output schema, so the description correctly takes on the burden of explaining return values (verdicts), the evidence/citation structure, and the distinction between failure modes. It also covers the two routing cases and the efficiency benefit. Combined with thorough annotations and complete parameter schema, this makes the description fully adequate for the tool's complexity.

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

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

Both parameters are fully described in the schema (claim with an example, tolerance_pct with its override behavior and default), so the description adds little new parameter-level detail. It does reference the tolerance concept ('percent-delta math') but this is already implied in the schema. With 100% schema coverage, a baseline score of 3 is appropriate.

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

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

The description explicitly defines the tool as a claim verification tool with specific natural-language triggers ('fact check', 'verify the claim that...'). It distinguishes its role by detailing the SEC EDGAR/XBRL fast path for financial claims and the grounded pipeline for all others, separating it from sibling tools like ask_pipeworx or deep_research. The statement 'Replaces 4–6 sequential calls' also clarifies its integrated scope.

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

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

The description provides an explicit trigger condition: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also explains the two internal routes, giving guidance on how claims are handled. However, it does not explicitly name alternative tools to use instead for other scenarios, nor does it state when not to use it, so it stops short of full exclusion guidance.

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