Jersey Opendata

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

Annotations already declare safe read and idempotency. Description adds context on default free model and optional paid Anthropic probe, plus return format. No contradictions. Moderate additional transparency beyond annotations.

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

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

Concise and front-loaded. First sentence states purpose, then model info, then return, then use cases. No fluff.

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

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

Covers parameters well, explains output format, provides typical use cases. Missing potential limitations (e.g., rate limits) but acceptable given annotations.

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

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

Schema has 100% coverage with descriptions. Description reiterates some params but adds practical context for 'context' (disambiguation). Does not add meaning beyond schema significantly.

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 action (probe LLMs), the resource (business/brand/product/topic), and the output (visibility scores per model). Differentiates from siblings like scan_competitor_ai_presence by focusing on visibility scoring.

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

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

Provides explicit use cases (AI-marketing audits, pre-launch brand checks, competitive monitoring) and notes default/optional models. Does not explicitly state when not to use or list alternatives, but context is clear.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds value by revealing that the tool routes to 3,899 tools across 932 sources, fills arguments, and returns structured answers with stable citation URIs. It does not contradict annotations. Minor gap: no mention of rate limits or potential latency.

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 most important guidance: 'PREFER OVER WEB SEARCH'. It is comprehensive but not overly verbose; every sentence adds value. Could be slightly trimmed (e.g., the list of sources is long), but overall efficient and well-structured.

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

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

Despite lacking an output schema, the description states the return is a 'structured answer with stable pipeworx:// citation URIs', which provides sufficient context for an agent. Given the tool's broad scope (routing to many sources), this is adequate. No major gaps identified.

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

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

Schema coverage is 100% with all parameters described. The description goes beyond by clarifying that the 'question' parameter accepts natural language and listing its aliases (query, q, prompt, etc.). Examples in the schema and description further illustrate usage. Baseline 3, plus 1 for added 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: answering factual questions about authoritative structured data (SEC filings, FDA, FRED, etc.). It uses specific verbs ('answers', 'routes') and distinguishes from siblings by naming ask_pipeworx_grounded and deep_research as alternatives.

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

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

Explicitly says 'PREFER OVER WEB SEARCH', provides clear examples of when to use (factual questions, specific phrasing), and explains when to step up to other tools (ask_pipeworx_grounded for hallucination-resistant answers, deep_research for broad queries). This gives the agent actionable decision criteria.

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

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

Annotations already cover readOnlyHint, idempotentHint, destructiveHint. The description adds operational details (routing, extraction, refusal reasons, extra LLM cost) 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?

The description is front-loaded with the core purpose and each sentence adds value, though slightly verbose; could be tightened slightly.

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

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

The description fully explains the tool's behavior, expected output (answer, evidence, confidence, etc.), refusal reasons, and cost implications, compensating for 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?

Schema coverage is 100% with all parameters documented as aliases for 'question'. The description does not add significant meaning beyond the schema, justifying the baseline score.

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 'hallucination-resistant answer mode for high-stakes reads' and explains it routes like ask_pipeworx but extracts answers solely from tool results, distinguishing it from its sibling ask_pipeworx.

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

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

Explicitly defines when to use: 'when an answer will be quoted, cited, or acted on...' and advises preferring ask_pipeworx for casual lookups, including the cost trade-off.

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 read-only, idempotent, non-destructive. Description adds extensive behavioral details: resolution process, fan-out, safety checks, edge cases like low-confidence matching, closed markets, illiquid spreads, and resolution-rule 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 very long and packed with details, which is appropriate for a complex tool. However, it lacks clear section breaks or formatting, making it dense. It front-loads the core purpose but could be more structured for readability.

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

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

Given the tool's complexity (3 parameters, no output schema), the description covers all relevant aspects: input formats, resolution logic, fan-out examples, response shapes, safety mechanisms, and edge cases. It is sufficiently 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?

All three parameters (depth, market, include_raw) are fully described in schema (100% coverage). Description adds examples, explains fan-out levels, and clarifies the impact of include_raw on response size, adding significant value beyond the schema.

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

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

The description clearly states it researches a Polymarket bet by pulling Pipeworx data, resolving the market, classifying, and fanning out to data packs. It distinguishes from sibling tools like polymarket_edges by focusing on individual bet research.

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

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

Explicitly states use cases ('should I bet on X', 'what does the data say about Y', 'is there edge in Z') and provides examples. Lacks explicit when-not-to-use or alternative tools, but the context is clear enough.

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

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

Annotations already declare readOnlyHint, openWorldHint, and idempotentHint. The description adds detailed behavioral context: data sources (SEC EDGAR/XBRL for companies, FAERS for drugs), specific metrics (revenue, net income, etc.), fiscal year handling, sorted results, and citation URIs. No contradictions.

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

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

The description is front-loaded with example queries and clear structure. While dense, every sentence adds value. Could be slightly trimmed without losing critical 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?

No output schema exists, but the description explains return format (paired data + citation URIs) and covers both entity types thoroughly. With only 2 fully-documented parameters, the description provides complete guidance for an AI agent.

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

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

Schema coverage is 100% with descriptions for both parameters. The description goes beyond by explaining what each type pulls (latest 10-K data for companies, adverse-event counts for drugs) and providing example values (tickers/CIKs, drug names). It adds substantial context but could be slightly more concise.

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

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

The description uses specific verbs like 'compare', 'rank', and 'head-to-head', clearly identifying the resource (2–5 companies or drugs). It explicitly distinguishes from siblings by stating 'ALWAYS PREFER over sequential single-pack lookups' and noting it replaces 8–15 lookups, which contrasts with 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?

Provides explicit query examples (e.g., 'compare X and Y', 'which is bigger') and a strong directive to prefer this over sequential lookups. However, it does not explicitly state when not to use it or mention alternatives like entity_profile for single entities.

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 context by identifying it as CKAN package_show and specifying returned fields (id, url, datastore_active), enhancing transparency beyond annotations.

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

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

Two concise sentences: first defines purpose and scope, second adds actionable details about resource fields. No wasted words.

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

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

Given the one-parameter schema and no output schema, the description adequately covers the return values by mentioning key resource fields. It provides sufficient context for the agent to understand the tool's output.

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

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

The schema describes the single parameter 'id' with an example. The description clarifies that it accepts id or slug, adding context not present in the schema.

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

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

The description clearly states the tool retrieves a full Jersey dataset record by id or slug, including its resources. It distinguishes from sibling tools like datastore_query by mentioning how to identify queryable resources.

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 obtaining a single dataset's details and hints at using it as a prerequisite for datastore_query, but does not explicitly state when to use this vs alternatives 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?

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and no destructiveness. The description adds that the tool only works on datastore_active resources, and what it returns (parsed records and field definitions). 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 two concise sentences with no redundancy. The first sentence states the purpose and prerequisite, the second adds return type and an example. No fluff.

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

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

Despite no output schema, the description explains the return type (parsed records plus field definitions) and gives a concrete example. It also mentions the underlying API. This is sufficient for a read-only query tool, though error conditions are omitted.

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 5 parameters. The description does not significantly add meaning beyond the schema, meeting the baseline for high coverage. The example mentioning Year/Age/Sex aligns with the filters parameter but does not provide new details.

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

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

The description clearly states the tool reads table rows from a Jersey resource via CKAN datastore_search, specifies it works only for datastore_active=true resources, and gives an example return (population projections). This distinguishes it from sibling tools, which are unrelated.

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 a prerequisite (resource must have datastore_active=true) and directs the user to get resource_id from dataset_details. It does not explicitly state when not to use it, but the context is clear enough.

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

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

Discloses behavioral traits beyond annotations: account requirement, expected duration (15-60s), return format (findings packet with gaps[]), and constraint that it is not open-web search. 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 verbose but well-structured, with each sentence earning its place. It front-loads critical info (account requirement) and uses clear paragraph breaks. Slightly longer than ideal 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 (2 params, no output schema), the description covers all necessary context: usage, limitations, return structure, time expectations, and alternatives. It leaves no gaps for agent decision-making.

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

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

Schema has 100% coverage, but description adds meaning: for 'depth' explains the facet counts (quick=3, standard=5, thorough=8); for 'question' clarifies that broad/multi-part is fine. This goes beyond the enum and type definitions.

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

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

The description clearly states the tool's purpose: 'Grounded multi-source research across Pipeworx's 932 STRUCTURED data sources' done in one call. It uses specific verbs ('decomposes', 'routes', 'returns') and distinguishes from siblings like ask_pipeworx and bet_research.

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

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

Explicitly provides when to use ('Best for broad/multi-part questions over structured data'), when not to use ('For a single lookup use ask_pipeworx', for breaking news prefer ask_pipeworx), and prerequisites (account required, depth needs paid plan).

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 and idempotentHint=true. Description adds that results include full schemas and curated examples, but does not discuss rate limits or auth. Adequately supplements 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?

Highly concise: three sentences that front-load the purpose, list key domains, and emphasize immediate usability. No wasted words or redundancy with schema/annotations.

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 meta-purpose and rich annotations/schema, the description fully explains when to use, what it returns, and how to act on results. No output schema needed as format is described.

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

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

Schema coverage is 100% with descriptions for all 6 parameters, so baseline is 3. Description adds value by explaining the spirit of the query parameter (natural language description), listing aliases, and providing real-world examples (e.g., 'analyze housing market trends').

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 'Find tools by describing the data or task' with a specific verb and resource. Distinguishes from siblings as a meta-tool for discovering other tools, not a domain-specific query tool.

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

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

Explicitly advises 'Call this FIRST' when many tools are available, setting context for when to use. Also describes output format (ready to call) and no need for second lookup, guiding immediate invocation.

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

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

Annotations already indicate readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds useful behavioral context: it makes one parallel call, returns specific data sources (SEC, XBRL, USPTO, news, GLEIF), and notes the USPTO PatentsView API sunset with soft-fail behavior. 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 with helpful examples and details. However, it is somewhat lengthy and could be broken into shorter sentences or bullet points for easier scanning. It earns its place but could be 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?

Despite having no output schema, the description thoroughly enumerates return fields (CIK, company_name, recent_filings with URIs, fundamentals, patents with caveat, news via fallback, LEI). It explains the internal fan-out and fallback logic, making it complete for a profile tool.

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

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

The input schema has 100% coverage with descriptions for both 'type' and 'value' parameters. The description reinforces that only 'company' type is supported and provides examples for ticker/CIK input, adding value beyond the schema.

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

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

The description explicitly states 'full cross-source profile of a US public company in ONE parallel call' and provides example queries like 'tell me about X' and 'company profile for Microsoft'. It distinguishes itself from sibling tools like resolve_entity by noting that names require prior resolution.

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

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

The description clearly says 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view' and 'Names not supported — use resolve_entity first if you only have a name'. This provides explicit when-to-use and alternative instructions.

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

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

Annotations already indicate destructiveHint=true, so description's 'Delete' adds no extra behavioral context. It doesn't mention irreversibility or effects on other data, which could be useful but is not necessary given 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?

Very concise: one sentence for action, plus two sentences for usage guidance. All content is front-loaded and directly relevant with no filler.

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

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

For a simple tool with one parameter and no output schema, the description provides sufficient context: what it does, when to use, and how it relates to siblings. Annotations cover safety aspects.

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

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

Schema coverage is 100% with parameter 'key' described as 'Memory key to delete'. The description does not add additional semantics beyond the schema, so baseline score applies.

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

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

Description explicitly states 'Delete a previously stored memory by key' with a clear verb and resource. It also distinguishes from siblings 'remember' and 'recall', which are for storing and retrieving memories respectively.

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 specific use cases: 'when context is stale, the task is done, or you want to clear sensitive data.' It also advises pairing with 'remember' and 'recall', though it doesn't explicitly list when not to use.

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

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

Annotations indicate readOnlyHint, idempotentHint, and non-destructive. The description confirms by stating it 'Fetches the page, extracts title/description/key links' and outputs a text blob. This adds behavioral context beyond annotations (e.g., fetching external content) without contradiction.

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

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

The description is two sentences with a bulleted list of use cases. It is front-loaded with the core functionality and has no redundant or extraneous content.

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

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

Given the tool's simplicity (2 params, no output schema), the description covers purpose, action, output format, and use cases. It does not address error scenarios but is sufficient for the agent to select and invoke correctly.

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

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

Schema description coverage is 100%, so the schema already documents both parameters. The description only restates the URL and max_links properties without adding new semantic details, meeting but not exceeding 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 generates a production-ready llms.txt file for any URL, specifying the verb (generate), resource (llms.txt), and output (standard markdown format). It distinguishes from siblings like scan_competitor_ai_presence by focusing solely on the llms.txt generation.

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

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

The description explicitly lists use cases (getting a client's site indexed, drafting for own project, auditing competitor) making when to use clear. It does not provide explicit when-not-to-use guidance, but the use cases are sufficiently specific.

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 readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds minimal value beyond noting the CKAN source and examples. 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?

Single sentence, concise, includes examples and source context. No wasted words or redundant information.

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

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

For a simple list tool with one optional parameter and strong annotations, the description provides adequate context, including the data source and example categories.

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 documented in the schema (100% coverage). Description does not add additional semantics 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 'List thematic groups/categories on opendata.gov.je', providing a specific verb and resource with concrete examples. It does not explicitly distinguish from sibling tools like list_organizations, but the context is 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?

No guidance on when to use this tool versus alternatives such as list_organizations or search_datasets. The description only gives examples but no usage context 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 provide readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds source specificity (CKAN organization_list) and organizational context (Jersey government), which is useful beyond the annotations.

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

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

Single sentence, front-loaded with verb and resource, no redundant words. Efficient and to the point.

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 operation with full annotations and a single parameter, the description is adequately complete. It mentions the source and example, though no output schema exists to describe return format.

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

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

Schema coverage is 100% for the single parameter 'limit', with a clear description in schema. Description does not add additional meaning beyond what the schema already 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 verb 'List' and the resource 'publishing organizations', specifies the domain (Jersey government departments/agencies) and the specific platform (opendata.gov.je CKAN), distinguishing it from sibling tools like list_groups.

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

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

No guidance on when to use this tool versus alternatives (e.g., list_groups, search_datasets). No when-not-to-use or prerequisites mentioned.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. Description adds that it returns specific fields and lists only active subscriptions by default, providing 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 concise sentences: first states purpose and return fields, second provides usage guidance. No unnecessary words.

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

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

Despite no output schema, description lists return fields. Parameter is fully documented in schema. Usage guidance is provided. Tool is simple and fully covered.

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

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

Schema coverage is 100% with parameter description. Description does not add extra meaning beyond schema, but it implies default behavior of listing only active subscriptions, which aligns with parameter semantics.

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

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

Description clearly states it lists active subscriptions and specifies exact return fields (id, type, params, etc.). This differentiates from siblings like 'subscribe' and 'unsubscribe' which are mutation tools.

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

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

Explicitly advises using this tool to review monitoring before adding more subscriptions or to find an id to cancel. This guides the agent on when to use this tool versus alternatives.

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

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

Beyond annotations (all false), the description discloses behavioral traits: rate-limited to 5 per identifier per day, free, doesn't count against tool-call quota, and that the team reads digests daily with signal affecting roadmap. This adds valuable context about side effects and limitations.

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

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

The description is concise (four sentences) and front-loaded with the primary purpose. Each sentence adds distinct value: purpose, usage scenarios, message constraints, and rate/quota info. No superfluous words, making it easy for an AI agent to parse quickly.

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

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

Given the tool's simplicity (3 parameters, no output schema), the description covers all necessary aspects: what to report, how to structure feedback, optional context, and operational limits (rate, quota). No gaps remain for an agent to use this tool effectively.

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

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

Schema coverage is 100%, but the description adds meaning by explaining enum values for 'type' and providing guidance on 'message' content and 'context' usage (e.g., 'pack slug'). This enhances understanding beyond the schema alone, though it doesn't introduce entirely new parameter insights.

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: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It specifies verb, resource, and enumerates use cases (bug, feature, data_gap, praise), distinguishing it from sibling tools like 'ask_pipeworx' or 'discover_tools' which serve different functions.

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

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

The description provides explicit when-to-use guidance: 'Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' It also gives constraints on message content ('describe the issue in terms of Pipeworx tools/packs') and mentions rate limits, offering comprehensive usage guidelines.

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

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

Annotations already declare read-only, open world, idempotent. Description adds value by explaining self-aggregating signal, no PII, caching behavior (5min-1h), and data source (CF analytics-engine). 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?

Well-structured: purpose sentence, bullet-point use cases, then data source and caching info. Every sentence adds value. 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 tool with one optional parameter and no output schema, description sufficiently explains return content (top tools, packs, count) and caching. Some users might want example output, but not essential.

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

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

Schema coverage is 100%. Description enhances parameter meaning: 'Shorter windows surface what's hot right now; longer windows show steady-state demand.' Adds context beyond enum values.

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

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

Description clearly states what the tool returns: 'top tools, top packs, and total call volume over a recent window' with specific verb 'Returns'. It differentiates from siblings like 'discover_tools' by focusing on trending data derived from agent calls.

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

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

Provides concrete use cases: discovering hot data sources, confirming canonical choice, aligning use case. While not explicitly stating when not to use, the context is clear and sufficient for a simple read tool.

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

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

Annotations indicate readOnlyHint, openWorldHint, idempotentHint as true. The description adds behavioral details like the fill check against live CLOB depth, the semantic anchor requiring Jaccard similarity, and the partition filter dropping placeholder slugs. It also clarifies that realizable_edge_pp ≤ 0 means the overround is not in the book, preventing incorrect trades. 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 dense but well-organized, starting with the critical requirement, then purpose, then structured paragraphs for each mode, response format, fill check, and cross-reference. Every sentence adds value without redundancy.

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

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

Given the tool's complexity (2 parameters, no output schema), the description is remarkably complete. It covers the entire workflow, expected response fields, and edge cases like fake overrounds and placeholder filtering. The absence of an output schema is compensated by the detailed description of the response structure.

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

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

Although the input schema has 100% coverage with descriptions, the tool description adds substantial meaning: examples of event slugs and topic seed questions, explanation of each mode's behavior, and the consequences of each parameter choice. This goes well beyond the schema's minimal 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 the tool finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It clearly distinguishes between single-event and cross-event modes, and the purpose is distinct from sibling tools like polymarket_edges or polymarket_fill_risk.

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

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

The description requires one of 'event' or 'topic' and explains when to use each mode: 'event (recommended for a specific market)' and 'topic (for cross-event scanning)'. It also warns against calling with no args and references polymarket_fill_risk for custom sizing, providing clear usage context.

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

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

Disclosures beyond annotations include cache behavior ('Cached 1h at the KV level'), model details, fed-market exclusion, and diagnostics. No contradictions with annotations (readOnlyHint, idempotentHint).

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, then detailed segments and knobs. While long, every sentence adds necessary context for a complex tool. Could be slightly more concise, but structure is logical.

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

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

No output schema, but description fully explains return structure (by_segment, fed_candidates, _diagnostics) and field details. Covers caching, knobs, and edge cases. Complete for agent use.

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

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

Schema coverage is 100%, but the description adds value by explaining parameter interactions (e.g., min_partition_leg_kelly for partition arbs, tradeable-edge knobs). Provides context beyond schema definitions.

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

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

The description clearly states the tool's purpose: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It distinguishes from siblings like polymarket_arbitrage by focusing on Pipeworx disagreement and providing detailed model families and segments.

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 tool is built for 'what should I bet on today' and explains tradeable-edge knobs. However, it does not explicitly advise when to use this tool versus siblings like polymarket_arbitrage, which would enhance 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 indicate read-only, idempotent, and non-destructive behavior. The description adds valuable context: snapshots are written only on cache-miss, gaps mean no scan that day, and decay computation uses daily closes. This goes beyond annotations without contradiction.

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

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

The description is comprehensive but slightly verbose. It is well-structured, starting with purpose, then response details, then limits. Every sentence adds value, though some could be combined. Front-loaded with core question.

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

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

Given no output schema, the description thoroughly explains the response format (tracked[], expired[], snapshot_dates[]) with field meanings, plus limits. It covers all expected aspects for agent invocation, leaving no ambiguity about return values.

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

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

Schema coverage is 100%, with clear descriptions for both 'days' and 'window'. The description repeats defaults and ranges already present in the schema, adding only minor context ('snapshot family'). No additional syntax or constraints beyond schema, so meets baseline expectation.

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: edge persistence and decay telemetry from daily snapshots, answering 'how long has this edge existed and is it shrinking?' It uses specific verbs (track, compute) and identifies the resource (polymarket_edges snapshots). Differentiates from sibling tools like polymarket_edges by focusing on time-series analysis rather than current snapshots.

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

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

The description explains when to use the tool via the example contrasting fresh vs. old edges, implying use for assessing edge longevity. It notes limits (60-day TTL, snapshot gaps) but lacks explicit when-not-to-use or direct comparison to siblings. Still provides sufficient context 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 indicate read-only, non-destructive, idempotent behavior. The description adds rich behavioral context: walks the ladder, returns fill details and verdicts, explains basket mode risks like forced directional risk. 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 dense but well-structured: starts with purpose, then requirements, then mode details, then warnings. Every sentence adds value. Could be slightly more concise but appropriate for the complexity.

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

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

No output schema, so the description fully explains return fields for both modes (e.g., top_of_book, vwap_fill_price, verdict for single-market; theoretical_sum, capture_ratio, thin_legs for basket). Also covers risk warnings, making it complete for agent use.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning by explaining side defaults for each mode, clarifying event/market meaning, and specifying size_usd default and range (10-1,000,000). This adds value beyond the schema.

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

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

The description clearly states it performs a 'Realizable-vs-theoretical edge check against live CLOB order-book depth' and distinguishes two modes (single-market and basket). It differentiates from siblings by explicitly saying to use this before acting on polymarket_arbitrage or polymarket_edges signals.

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

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

Explicitly states prerequisites: requires one of `market` or `event`. Provides when-to-use guidance: before acting on arbitrage signals or trades above ~$500. Warns against theoretical overrounds on thin books and partial basket fills.

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

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

Beyond annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint), the description extensively details behaviors: compatibility warnings for unmatched bet shapes, temporal alignment checks, skipped type/subtype counters. 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 (TWO MODES, RESPONSE, SAFETY FIELDS) and front-loaded with the core purpose. Minor redundancy could be trimmed, but it remains efficient for the complexity.

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

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

Given no output schema, the description thoroughly covers return fields: leg-by-leg prices, spread, compatibility warning cases, temporal alignment, and skipped counters. It addresses edge cases and potential agent confusion, ensuring completeness.

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

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

Schema coverage is 100%, but the description adds value by explaining the topic list (10 macros) and the override behavior of the explicit event parameters. It clarifies how parameters interact, e.g., 'auto-fetch the matching event' and 'overrides the topic-mapped side.'

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

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

The description clearly identifies the tool's purpose: computing cross-venue spreads between Kalshi and Polymarket for the same resolving question. It uses specific verbs and resources, and distinguishes from sibling tools like 'polymarket_arbitrage' by focusing on data from two venues.

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

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

The description explains two modes (topic shortcuts and explicit pairing) and provides guidance on when to use each. It warns that most pre-mapped topics return compatibility warnings, setting expectations. However, it does not explicitly compare to alternative tools like 'polymarket_arbitrage' or 'bet_research'.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint. The description adds value by explaining scoping to identifier and listing behavior when key is omitted, but this complements rather than critically augments 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?

Three concise sentences with no wasted words. Front-loaded with the core action, followed by usage context, then scoping. Excellent structure.

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

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

Given one optional parameter, no output schema, and comprehensive annotations, the description is fully complete. It covers purpose, usage, scope, and pairing without requiring additional information.

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 of the 'key' parameter is already provided in the schema. The description adds no new parameter-level information beyond what the schema already specifies.

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 retrieves a value saved via 'remember' or lists all saved keys. It distinguishes itself from sibling tools like 'remember' and 'forget' by specifying the retrieval action.

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

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

Provides explicit when-to-use guidance: 'look up context the agent stored earlier' and avoids re-deriving. Also notes scope and pairing with remember/forget, giving a complete usage picture.

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

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

Annotations already declare readOnly, openWorld, idempotent, non-destructive. Description adds value by explaining mark_read behavior (flags as read so next call shows newer ones) and describes return fields, going beyond annotations. No contradictions.

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

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

Description is a single, front-loaded paragraph of 3 sentences. Every sentence adds value: purpose, return fields, filtering options, mark_read behavior, and alternative access. No wasted words.

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

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

With no output schema, description sufficiently explains return values (source, citation_uri, payload). It covers all 5 parameters, mentions polling suitability, and provides an alternative URL. Complete for a read-only, well-annotated tool.

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

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

Schema coverage is 100%, so baseline is 3. Description adds minor value: gives example filter type 'sec_8k', mentions ISO timestamp for since, and explains mark_read effect. Most parameter semantics are already clear from schema descriptions.

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

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

Description clearly states it pulls fired events from subscription feed and returns recent alerts. Specifies key fields (source, citation_uri, payload) and distinct resource (alerts feed), distinguishing it from siblings like list_subscriptions or recent_changes.

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

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

Mentions polling works fine and provides an alternative URL for scripts/dashboards, giving usage context. However, it does not explicitly state when to use this tool vs alternatives like list_subscriptions or when not to use it, so it is clear but lacks exclusions.

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

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

Annotations already indicate read-only, idempotent, open-world, and non-destructive behavior. The description adds significant context: internal fan-out to multiple sources (SEC EDGAR, GDELT/GNews, USPTO), fallback mechanism from GDELT to GNews on rate limits or 5xx, and USPTO soft-fail until reactivation. It also describes the output structure. 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, information-dense paragraph that front-loads example queries, then explains the tool's operation, parameter details, output, and sibling distinction. Every sentence earns its place with no redundancy or fluff.

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

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

Given 3 required parameters, no output schema, and no nested objects, the description provides a good overview of the return structure (changes[], total_changes, citation URIs), source fallback logic, and parameter formats. It could be more explicit about output limits or pagination, but overall it is fairly 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%, but the description adds value by explaining the 'since' parameter in detail (ISO date or relative shorthand, examples), suggests a typical value ('30d' or '1m'), confirms 'type' only supports 'company', and gives examples for 'value' (ticker or CIK). This guidance goes beyond the schema descriptions.

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

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

The description uses specific verbs like 'change feed' and 'fans out' to multiple sources, clearly indicating the tool's purpose. It provides example queries ('What's new with X') and explicitly distinguishes itself from the sibling 'entity_profile' for static profiles.

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

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

The description gives clear guidance on when to use this tool (e.g., for recent changes over a window) and when to use 'entity_profile' instead (static profile regardless of window). It also offers parameter best practices ('Use "30d" or "1m" for typical monitoring'). However, it does not explicitly state when NOT to use this tool beyond that single sibling reference.

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 show idempotentHint=true and destructiveHint=false. The description adds valuable context: scope by user identifier, persistence differences between authenticated (permanent) and anonymous (24-hour) sessions, and that data is stored as key-value pairs. No contradictions.

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

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

Four concise sentences, each with a distinct purpose: purpose, usage, behavioral trait, and sibling reference. Front-loaded with the core function. No redundant or missing 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 two-parameter write tool with no output schema, the description covers everything needed: what it does, when to use it, how data is scoped, and persistence behavior. Context signals confirm no missing 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 descriptions for both key and value. The description adds contextual usage examples ('memory key (e.g., "subject_property", "target_ticker")') and clarifies that the value is any text, reinforcing the schema but not significantly expanding meaning.

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

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

The description clearly states the tool saves data for later reuse, specifying the resource (key-value pair memory) and the verb (save). It distinguishes from sibling tools recall and forget by explicitly mentioning them.

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

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

Gives explicit guidance: 'Use when you discover something worth carrying forward' and explains why ('so you don't have to look it up again'). It pairs with recall and forget but doesn't elaborate on when not to use or compare to other storing mechanisms like datastore_query.

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 true, and destructiveHint false. The description adds that each call cascades through several lookup endpoints internally, replacing 2-3 manual lookups, and provides citation URIs. No contradiction with annotations.

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

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

The description is informative but slightly lengthy. It starts with examples, then usage guidance, then details. Every sentence adds value, but could be more streamlined without losing essential information.

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

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

No output schema, but the description fully explains what is returned for each type: for company (ticker, 10-digit CIK, company_name, citation URI) and for drug (RxCUI, ingredient, brand, citation). Covers input and output comprehensively for a simple 2-param tool.

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

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

Schema coverage is 100%, but the description adds substantial meaning: for 'type', it lists supported types and their return values; for 'value', it provides examples and acceptable formats (ticker, CIK, name for company; brand/generic for drug), going 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 resolves user-spoken names to canonical identifiers, with examples like 'What's the ticker for...' and explicit supported types (company, drug). It distinguishes itself from sibling tools by being the primary tool for name-to-ID conversion.

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 FIRST whenever you have a name but need an ID.' Provides detailed input and output for each type, including accepted formats (ticker, CIK, name for company; brand/generic for drug). Contrasts with tools that require IDs as input.

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

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

Annotations already declare read-only, idempotent, non-destructive behavior. Description adds that it probes each entity with 'ai_visibility_check' and returns a ranked list with score, confidence, and signal density, which is informative 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, front-loaded with core functionality, followed by use case and return format. Every sentence adds value; no fluff.

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

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

No output schema, but description adequately describes return values (ranked list with score, confidence, signal density). Explains process (calls ai_visibility_check). Could mention entity count constraints (2-8 implied by schema's first-entry treatment), but adequate overall.

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

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

Schema covers all 4 parameters (100% description coverage). Description adds context: first entity treated as 'subject' for narrative, and optionality of 'models' and '_apiKey'. This adds meaningful nuance despite high schema coverage.

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

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

Description clearly states it compares AI visibility across multiple entities side-by-side, ranks by score, and surfaces most/least recognized. Distinguishes from sibling 'ai_visibility_check' by emphasizing multi-entity comparison.

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

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

Provides explicit use case ('competitive AI-marketing audits') and example question. Implicitly contrasts with single-entity probe 'ai_visibility_check', but lacks explicit when-not-to-use or alternative tool names.

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

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

Annotations indicate readOnly, openWorld, idempotent, and non-destructive. The description adds detailed behavioral context: fans out across two external APIs, returns specific fields, handles partial failures gracefully, and mentions that bundlephobia's first measurement can take 5-30 seconds. This goes well beyond annotations.

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

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

The description is well-structured with a clear purpose first, then details. It is somewhat lengthy due to listing return fields, but each sentence adds value. Minor conciseness improvements could be made, but it remains efficient for the tool's complexity.

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

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

No output schema exists, so the description must fully explain what is returned. It does so explicitly: summary block, per-advisory detail, links, and alternative versions. It also covers partial failures and timeout behavior, making it complete for the intended 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%, but the description adds valuable context: explains that scoped packages are accepted for 'package' and that 'version' defaults to latest when omitted. This clarifies usage beyond the schema.

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

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

The description clearly states it is a composite check for evaluating npm packages, citing specific use cases like 'is X safe / popular / small' and 'what does adding lodash cost me'. It distinguishes from siblings by noting that for other ecosystems (PyPI, Maven, etc.) one should use deps.dev:version directly.

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

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

Provides explicit instructions on when to use the tool ('whenever an agent asks...') and clarifies that it is for npm only, pointing to alternatives for other ecosystems. Also warns about potential delays from bundlephobia's first measurement and how partial failures are handled.

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 readOnly, idempotent, non-destructive hints. The description adds value by specifying the return structure (titles/descriptions/resources in English) and the underlying API, going beyond annotations without contradiction.

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

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

Two concise sentences: the first front-loads purpose, source, and API; the second provides examples. Every word adds value with no fluff.

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

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

The description sufficiently explains what the tool returns (matching datasets with metadata) given the lack of output schema. It could mention pagination implied by start/rows params, but the schema covers that. Overall complete for its complexity.

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

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

Schema coverage is 100% with good descriptions. The description adds helpful example values for query and fq parameters (e.g., 'population', 'organization:statistics-jersey'), enhancing usability 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 verb 'Search' and the specific resource 'Government of Jersey open-data catalogue', distinguishing it from sibling tools like bet_research or search_within by specifying the domain (Jersey government data) and source API (CKAN package_search).

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

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

The description implies when to use the tool (searching Jersey open data) but does not explicitly exclude alternatives or mention when not to use it. The context is clear, but exclusion guidance is missing.

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 (read-only, open-world, idempotent), the description adds specific behavioral details: BGE-base-en embeddings, cosine similarity, 500-char overlapping windows, 200K char cap with truncation/flagging, and passage offsets for verification.

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

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

Single paragraph, front-loaded with purpose, well-structured. Every sentence adds value, though it could be slightly tighter. No wasted words.

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

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

Covers purpose, usage scenario, technical details, constraints, and return value semantics (passages with offsets). No output schema, but description explains what is returned sufficiently for selection and invocation.

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

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

Schema has 100% coverage with descriptions. The tool description adds context about usage ('pass the text you already pulled') but does not provide new structural details beyond schema descriptions. 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 performs semantic search inside a fetched record, gives concrete examples (SEC 10-K, article, tool result), and distinguishes itself from sibling tools like ask_pipeworx_grounded by explaining their 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?

Provides explicit when-to-use guidance ('Use when the record is too big to cram into the prompt'), saving context, and mentions a complementary tool. Lacks explicit when-not-to-use or alternative scenarios, but context is clear.

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

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

Discloses that anonymous/BYO cannot persist, lists delivery channels with constraints (phone verification, 10/day cap). Annotations correctly reflect non-readonly and non-destructive nature; description adds significant behavioral context.

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

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

Well-structured with bullet points and front-loaded purpose. Contains necessary details but is somewhat lengthy; every sentence adds value.

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

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

Given complexity (multiple types, delivery channels, prerequisites), description is thorough. No output schema but return value stated. Covers all essential aspects for correct agent 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?

Input schema has 100% coverage, but description adds meaningful examples and constraints for each subscription type and delivery option, exceeding baseline. Slight room for more detail on webhook signing.

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 'Create a proactive monitoring subscription' and specifies it returns a subscription id. It distinguishes from sibling tools like list_subscriptions and unsubscribe by focusing on creation.

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

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

Mentions requirement for Pipeworx OAuth account and gives detailed examples of subscription types. Implicitly clarifies when to use (to set up monitoring) vs siblings, but lacks explicit when-not 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, destructiveHint. Description adds behavioral details: returns live catalog-sourced example questions with exact tool+argument shapes. No contradictions.

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

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

Description is well-structured with front-loaded purpose, includes query pattern examples, a list of categories, and usage notes. Slightly long but every sentence adds value.

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

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

No output schema exists, but description fully explains return content (category-bucketed example questions with tool+argument shapes). Covers parameter and usage context comprehensively for an onboarding 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 has 100% coverage with one optional string parameter. Description adds meaning by listing possible topic values (finance, pharma, etc.) and explaining behavior when omitted ('cross-category spread'). Adds value beyond schema.

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

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

Description clearly states it is an onboarding entry point that returns category-bucketed example questions with tool+argument shapes. It lists specific categories and distinguishes from siblings by noting the use case of learning what Pipeworx can do.

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 'Call with no arguments for the full spread, or pass topic to focus' and 'Use this FIRST when you do not yet know what Pipeworx can do for you'. Provides clear when-to-use guidance and mentions alternative tools like ask_pipeworx.

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), the description discloses that rows are deactivated rather than deleted, and historical events remain available. This adds meaningful 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?

Two sentences, front-loaded with the core action, and every sentence adds essential value. No wasted words.

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

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

For a simple one-parameter tool with no output schema, the description covers ownership, mutation behavior, and impact on historical data—sufficient for correct usage.

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 'id' is described as 'Subscription id (uuid) returned by subscribe.' Schema coverage is 100%, and the description adds clarity by linking to the subscribe tool.

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 'Cancel a subscription by id'—a specific verb-resource pair. It clearly distinguishes from sibling tools like 'subscribe' and 'list_subscriptions'.

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

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

Explicitly explains ownership enforcement ('you can only cancel your own subscriptions') and behavioral detail ('row is deactivated not deleted'). This provides clear context for when and how to use the tool.

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

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

Annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint) are fully disclosed, and the description adds valuable behavioral context: return verdict types (confirmed, refuted, etc.), extracted structured form, citation, and percent delta. It also notes it replaces 4-6 calls, giving insight into efficiency.

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

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

Description is front-loaded with query examples, then states purpose, domain limitations, return structure, and benefit. Every sentence adds distinct value with no redundancy, packed into a few well-structured sentences.

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

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

Despite no output schema, the description fully specifies return value structure (verdict, structured form, citation, delta). Domain constraints, parameter format, and use-case are clear, making the tool self-contained for an AI agent.

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

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

Schema coverage is 100% for the single parameter, and the schema already provides a description and examples. The tool description reinforces the parameter's meaning with natural-language claim examples, adding value beyond 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 performs natural-language claim verification against authoritative sources for company-financial claims, with specific query examples (Is it true that..., fact check). It distinguishes itself by specifying domain and mentioning it replaces multiple sequential calls, though it doesn't explicitly contrast with sibling tools like 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 'Use whenever the agent needs to check whether something a user said is factually correct.' However, it only mentions v1 supports company-financial claims without explicitly stating when not to use it for other domains, nor does it mention alternatives among sibling tools.

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