Data Howardcounty

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

Annotations already indicate idempotent, read-only, open-world, non-destructive. Description adds per-model return structure and clarifies cost implications (BYO key for Anthropic), going 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?

Four sentences with no wasted words. Front-loaded with main action, then clarifies options, return format, and use cases. 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?

Despite no output schema, description adequately outlines return structure (per-model {score, confidence, signals, raw_response} + combined view). For a probe tool with moderate complexity, this is sufficient.

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

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

Schema descriptions cover all 4 parameters at 100%, so baseline is 3. Description adds minor context (e.g., 'free default' for models), but does not significantly enhance understanding beyond schema.

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

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

Description clearly states the tool probes LLMs for knowledge about an entity and scores visibility. It specifies the default model and optional Anthropic probe, and distinguishes from siblings like '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 lists use cases (AI-marketing audits, pre-launch brand checks, competitive monitoring) and explains when to provide Anthropic API key. Lacks explicit when-not-to-use but context is sufficient.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint. Description adds that it returns structured answers with citations and routes to many tools, giving useful context 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?

The description is detailed but somewhat verbose, spanning multiple paragraphs. It is front-loaded with key guidance, but could be more concise without sacrificing clarity.

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

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

Given the tool's complexity (6 param aliases, no output schema, many siblings), the description fully explains capabilities, usage, alternatives, and examples. Completes the agent's understanding.

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. The description adds examples and clarifies multiple aliases, providing slight extra value. Baseline 3 is exceeded by practical usage context.

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

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

The description clearly states the tool answers factual questions using authoritative structured data, distinguishing it from web search and siblings like ask_pipeworx_grounded and deep_research. It specifies the verb 'ask' and resource 'Pipeworx' with a broad range of topics.

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

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

Explicitly says 'PREFER OVER WEB SEARCH' and 'START HERE for most questions', lists when to use alternatives (grounded for hallucination-resistant answers, deep_research for broad queries). Provides concrete examples and question types.

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 the annotations (readOnlyHint, openWorldHint, idempotentHint), the description details the extraction process using only tool results, the exact response format with fields (answer, evidence, confidence, etc.), and explicit refusal reasons. It also discloses the cost of an extra LLM call. No contradiction with annotations.

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

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

The description is front-loaded with key information and each sentence serves a purpose. However, it is somewhat lengthy; a slightly more compact version could improve efficiency. Still, it avoids unnecessary repetition.

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

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

Given the absence of an output schema, the description fully compensates by detailing the return structure (answer, evidence, confidence, source, fetched_at, refusal_reason) and all possible refusal reasons. It also explains the cost trade-off with ask_pipeworx, making the tool's behavior fully understandable.

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 being aliases for 'question'. The description adds that aliases include query, q, prompt, text, input, but this is already indicated in the schema. No additional meaning beyond what the schema provides, so baseline of 3 is appropriate.

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

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

The description clearly defines the tool as a hallucination-resistant answer mode for high-stakes reads. It specifies the behavior: routing through tools, fetching data, and extracting answers solely from results. It explicitly distinguishes from sibling ask_pipeworx by noting the extra LLM call and use case differentiation.

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

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

The description provides explicit guidance: use when answers will be quoted or acted on and factuality is critical (financial, legal, medical, public statements). It also advises preferring ask_pipeworx for casual lookups, offering clear when-to-use and when-not-to guidance.

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

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

The description goes far beyond annotations, detailing resolution confidence levels, parent event extraction, news fallback mechanisms, market closed/inactive status, wide-spread illiquidity, and resolution-rule risk. It provides comprehensive behavioral insights, ensuring the agent understands all safety and edge cases.

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

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

The description is long but well-structured with sections (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, etc.). It front-loads the main purpose and provides detailed, earned content. Minor redundancy could be trimmed, but overall it's appropriately sized 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?

Despite lacking an output schema, the description thoroughly explains the response shape (result.market, result.analysis, result.evidence, etc.), includes edge cases like low-confidence matches and closed markets, and covers resolution-rule risk. It is fully sufficient for an agent to understand outputs.

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, but the tool description adds significant value: examples for market input, depth options with explanations, and include_raw with size trade-offs. This extra context helps agents choose parameters effectively.

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 Polymarket bets by pulling Pipeworx data, with specific verb 'Research' and resource 'Polymarket bet'. It distinguishes itself from sibling tools like polymarket_edges and validate_claim by focusing on data retrieval and evidence packet 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: 'should I bet on X', 'what does the data say about Y', 'is there edge in Z'. It provides clear context but does not mention when not to use this tool or suggest alternative tools, leaving some room for improvement.

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 readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. Description adds valuable behavioral context: it pulls latest 10-K data, handles fiscal year differences, returns sorted results by primary metric, and includes 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 a single paragraph but front-loaded with common query phrases. Every sentence provides essential information. Could be slightly more structured (e.g., bullet points) but remains concise and informative.

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 all key aspects: what data is fetched per type, how results are organized, citation URIs, and performance advantage over sequential lookups. No output schema, but description sufficiently describes return format. Leaves minimal open questions.

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

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

Schema coverage is 100% with descriptions for both parameters. Description adds practical examples (tickers for company, drug names) and explains how the 'type' parameter affects data pulled (revenue/profit vs. adverse events/trials), exceeding schema verbatim.

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

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

Description uses specific verbs ('compare', 'rank') and clearly identifies the resource ('companies or drugs'). It lists example queries and explicitly distinguishes from sequential single-entity lookups, making the purpose unmistakable.

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

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

Explicitly states 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.' Provides concrete when-to-use scenarios via example queries and differentiates between entity types, guiding the agent to choose this tool over alternatives.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true, openWorldHint=true, so the safety and idempotency are clear. The description adds workflow context (use resource_id with another tool) but no additional behavioral traits 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 two sentences: first sentence states the purpose, second explains the return value and next step. No unnecessary words, well front-loaded.

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

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

Despite no output schema, the description lists the returned fields (resource_id, name, description, category, update date) and suggests a follow-up action. Pagination and defaults are covered in the schema, so the combination is adequate for this simple tool.

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

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

Schema description coverage is 100%, so the schema already documents all three parameters. The description mentions 'by keyword' which aligns with the query parameter but does not add new information about parameter semantics beyond the schema.

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

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

Description clearly states the tool searches the Howard County Open Data catalog by keyword, specifying the resource (open datasets) and action (search). It distinguishes from sibling tools like 'query' or 'search_within' which are not specific to this catalog.

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 context by noting that the returned resource_id should be passed to 'query/metadata', but it does not explicitly state when to use this tool over alternatives or provide when-not-to-use guidance.

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

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

The description adds rich behavioral context beyond annotations: it decomposes questions into facets, routes to tools in parallel, returns findings packet with evidence, confidence, source, fetched_at, pipeworx:// citations, and gaps[]. It also mentions expected latency (15-60s) and limitations (returns empty gaps for topics not in structured catalog).

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

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

The description is relatively long but well-organized: starts with account requirement and alternative, then describes functionality, then use cases and caveats. Every sentence adds value, though could be slightly more concise for an AI agent.

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

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

The description fully compensates for the lack of output schema by detailing the return format (findings packet with evidence, confidence, source, citations, gaps[]). It also explains latency, prerequisites, and limitations, making it self-contained for an agent to decide on invocation.

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

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

Schema coverage is 100%, so baseline 3. The description adds meaning: question should be natural language and broad/multi-part is fine; depth defaults to 'standard', 'thorough' requires a paid plan. This provides context beyond the enum 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 it performs grounded multi-source research across structured data sources, using a specific verb-resource combination. It distinguishes from sibling ask_pipeworx by specifying it is for broad/multi-part questions, not single lookups or breaking news.

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

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

Explicitly states when to use (broad/multi-part questions over structured data) and when not to use (single lookups use ask_pipeworx, breaking news use ask_pipeworx). Also mentions account requirements and provides an alternative tool if not signed in.

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

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

Annotations already indicate read-only and idempotent. Description adds that it returns top-N tools with full schemas ready to call, providing useful behavioral context without contradiction.

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

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

Well-structured and front-loaded, but slightly verbose with redundant synonyms. Every sentence earns its place overall.

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 input parameters and return format well, given no output schema. Could mention semantic search or variation, but sufficient for a discovery 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 description adds minimal parameter info beyond schema. Baseline 3 applies; description doesn't enhance parameter understanding 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?

The description clearly states the tool finds tools by describing data or task, lists specific domains, and distinguishes from siblings by advising to call this first when exploring options.

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

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

Explicitly advises 'Call this FIRST when you have many tools available and want to see the option set', implying when not to use it. Clear context for browsing vs. direct answers.

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

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

Annotations already provide readOnlyHint, idempotentHint, openWorldHint, destructiveHint. Description adds valuable behavioral details: fans across multiple sources, USPTO patents API sunset May 2025 (soft-fails), GDELT→GNews fallback, and specific return fields. No contradictions with annotations.

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

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

The description is relatively long but packed with useful information in a front-loaded manner (example queries first). Every sentence adds value, though slight trimming could improve conciseness without losing content.

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

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

Despite no output schema, the description thoroughly explains return values: cik, company_name, recent_filings with URIs, fundamentals, patents with sunset note, news via fallback, LEI. For a complex aggregation tool, this is sufficiently 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%, so parameters are already documented. However, description adds context: type is only 'company' currently, value can be ticker or zero-padded CIK, and names not supported (recommending resolve_entity). This adds meaning beyond the schema's enum and description.

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

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

Description starts with concrete example queries like 'Tell me about X' and 'research Acme', clearly defining the tool as a comprehensive company profile. It states 'full cross-source profile of a US public company in ONE parallel call', which is a specific verb+resource that distinguishes it from siblings like compare_entities or resolve_entity.

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

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

Explicitly says 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view', guiding when to use. Also states 'Names not supported (use resolve_entity first if you only have a name)', providing a clear alternative and when not to use this tool.

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

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

Annotations already mark destructiveHint=true and readOnlyHint=false. The description adds usage context (sensitive data, stale context) beyond what annotations provide, but doesn't elaborate on side effects like irreversibility. Still adds value.

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

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

Two concise sentences, front-loaded with the core action. Every word earns its place with no redundancy.

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

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

For a simple tool with one parameter and no output schema, the description covers purpose, usage, parameter, and sibling relationships completely. Annotations complement it well.

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

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

Schema coverage is 100% and the 'key' parameter is described as 'Memory key to delete.' The tool description does not add more meaning beyond what the schema already provides, so baseline 3 is appropriate.

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

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

The description clearly states 'Delete a previously stored memory by key.' It uses a specific verb (delete) and resource (memory), and the sibling tool names (remember, recall) indicate its distinct inverse role.

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 lists when to use: 'when context is stale, the task is done, or you want to clear sensitive data.' Also pairs with remember and recall, guiding the agent on tool selection.

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

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

Description explains the tool fetches the page, extracts title/description/key links, and emits markdown. Annotations already cover read-only, idempotent, non-destructive, so description adds process details 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?

Four sentences, front-loaded with purpose, no redundant or missing information. Each sentence adds value.

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

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

With 2 parameters and no output schema, the description covers input, process, output format, and use cases. Adequate for an AI 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?

Both parameters have 100% schema description coverage. The description adds an example for url and restates default/max for max_links, but adds minimal new meaning beyond schema.

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

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

Clearly states the tool generates an llms.txt file for a URL, describes the process (fetches, extracts, emits), and specifies output format. Distinct from sibling tools like scan_competitor_ai_presence.

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

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

Lists three explicit use cases (client site indexing, own project drafting, competitor auditing) but does not mention when not to use it or compare to alternatives. Still provides clear context.

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

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

Annotations already indicate read-only, idempotent, and nondestructive behavior. The description adds value by specifying the return fields (id, type, params, etc.), but does not disclose any additional behavioral traits such as pagination or rate limits. Overall, good but not exhaustive.

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

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

The description is three sentences with no wasted words. The first sentence front-loads the core purpose, the second lists return fields, and the third provides usage guidance. Every sentence earns its place.

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

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

Given the simplicity of the tool (one optional parameter, no output schema), the description covers purpose, return value, and usage guidance. Combined with comprehensive annotations (readOnlyHint, etc.), the description is complete for effective 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% with the parameter 'include_inactive' fully described. The description does not add any further meaning to the parameter, so a baseline score of 3 is appropriate.

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

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

The description clearly states 'List the caller's active subscriptions' with a specific verb and resource. It distinguishes from sibling tools like subscribe and unsubscribe by focusing on the list operation. The mention of return fields solidifies the purpose.

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

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

The description explicitly advises using this tool to review current subscriptions before adding more and to find an ID to cancel, providing clear when-to-use context. This guides the agent to use it in conjunction with subscribe and unsubscribe, leveraging sibling relationships.

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

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

Annotations already declare readOnlyHint and destructiveHint false, indicating a safe read operation. The description adds value by specifying exactly what metadata is returned (columns, types, etc.) and the data source (Howard County Open Data), which goes beyond annotation information.

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, front-loaded sentence of 21 words. It efficiently conveys the tool's purpose and output without any redundancy.

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

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

Despite lacking an output schema, the description enumerates the exact fields returned (columns, types, row count, category, last-updated). The tool is simple with one parameter and safe annotations, making the description fully adequate for an agent to understand and invoke it.

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

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

Schema coverage is 100% with a clear description of the resource_id parameter. The description provides an example but does not add substantial meaning beyond what is already 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 returns a dataset's schema and metadata, listing specific fields (columns, types, row count, category, last-updated) and provides an example resource_id. It is distinct from sibling tools like 'datasets' which likely lists datasets.

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 retrieving metadata of a specific dataset, but does not explicitly mention when not to use it or alternatives such as 'datasets' for listing all datasets. However, the context is clear enough for an AI agent.

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 daily rate limit of 5 per identifier, that it doesn't count against tool-call quota, and that the team reads digests daily. Adds important 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 paragraph: purpose first, then use cases, then dos/don'ts, then operational details. Every sentence contributes value. No redundancy.

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

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

For a feedback tool with only 3 parameters, the description covers all necessary context: usage triggers, content guidelines, rate limits, and quota info. 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 coverage is 100% with clear parameter descriptions. The description adds some usage guidance (e.g., 'describe the issue in terms of Pipeworx tools/packs') but doesn't significantly extend the schema's meanings. Baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose: sending feedback about bugs, missing features, data gaps, or praise. It distinguishes itself from sibling tools by being a feedback submission tool, not an analysis or research 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 specifies when to use each feedback type (bug, feature/data_gap, praise). Provides a 'don't' rule (no pasting end-user prompts) and mentions rate limits and quota-free usage. Clear and actionable.

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

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

Annotations already provide readOnlyHint, openWorldHint, etc. The description adds that it's self-aggregating, no PII, and cached 5min-1h, which is valuable context beyond the annotations.

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

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

Three sentences with no waste. Front-loaded with the main functionality, followed by use cases, then technical details. Every sentence earns its place.

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 rich annotations, the description fully covers purpose, usage, and behavior. No gaps.

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

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

Schema coverage is 100% for the single parameter. The description adds meaning by explaining that shorter windows surface hot trends while longer windows show steady-state demand, going beyond the 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?

The description clearly states it returns top tools, top packs, and total call volume over a recent window (24h, 7d, or 30d). The verb 'returns' and specific resources differentiate it from siblings like 'discover_tools' and '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 lists three use cases (discovering hot data sources, confirming popular tools, checking alignment). It doesn't explicitly state when not to use, but the use cases are clear and context signals are sufficient.

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

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

Annotations declare readOnlyHint, etc. Description adds extensive behavioral details: semantic anchor with Jaccard threshold, partition filter for placeholders, fill check against live CLOB depth. 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: starts with purpose, then details each mode, then semantic anchor, partition filter, fill check. Could be slightly more compact, but the density of information justifies the length.

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

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

Given the tool's complexity (two modes, multiple checks, fill analysis), the description covers all relevant aspects: invocation, internal logic, edge cases, response structure. No output schema, but response fields are described. References sibling tool for additional needs.

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

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

Schema coverage is 100% with descriptions for both parameters. The description adds deeper meaning: explains what event slug and topic seed question look like, and what happens when no args are passed. Significantly enriches parameter understanding.

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

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

The description clearly states the tool finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes two modes (event and topic) and a default trending scan, differentiating it from sibling tools like 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?

Provides explicit when-to-use guidance: NO args for trending scan, event for specific market, topic for cross-event scanning. Also tells when not to trade (realizable_edge_pp ≤ 0) and references sibling tool for custom sizing.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false. The description adds extensive behavioral detail: edge_pp_net is after slippage, kelly_fraction capped at 0.25, 24h-move warning, caching at KV level for 1 hour, and detailed explanation of model families and filters. No contradiction with annotations.

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

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

The description is long but well-structured with clear sections (segments, knobs, response structure). Front-loads the main purpose. While verbose, every sentence adds value given the tool's complexity. Could be slightly more concise but still effective.

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

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

Given 9 parameters, no output schema, and complex segmentation, the description is highly complete. It explains the by_segment response structure, diagnostics field, filter knobs, and caching behavior. Covers edge cases like Fed bets and partition placeholder filter. Users can fully understand tool behavior without external docs.

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

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

Schema coverage is 100%, but the description adds significant meaning beyond schema descriptions. For example, it explains the rationale behind min_kelly ('Skips opportunities that are too small to bet sensibly'), slippage_pp assumptions (20-50bp typical), and min_partition_leg_kelly justification. Every parameter receives additional 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?

Clearly states it scans top Polymarket markets for opportunities where Pipeworx data disagrees with market price. Distinguishes from sibling tools like polymarket_arbitrage and polymarket_edge_tracker by detailing its unique segmentation (model-driven, structural arbitrage, concentrated longshot) and 'what should I bet on today' purpose.

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

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

Explicitly says 'Built for what should I bet on today' and explains how agents can discover opportunities without paging hundreds of markets. Provides guidance on knobs like min_liquidity, max_spread_pp, and slippage_pp, and notes Fed bets are excluded from ranking. Could be improved by stating when not to use this tool vs alternatives.

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

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

Annotations already declare readOnly, openWorld, idempotent. Description adds context about snapshot gaps, decay computation from daily closes, and response field meanings, 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?

Description is fairly long but front-loaded with purpose, then details response and limits. Every sentence adds value, though could be slightly more concise.

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

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

No output schema, but description fully specifies response fields (tracked, expired, snapshot_dates) with details on each field's meaning, including negative edge sign and limits. Very complete for a complex telemetry 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 default values and clarifies the 'window' as a snapshot family, providing extra context beyond the schema.

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

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

The description clearly states the tool provides 'edge persistence and decay telemetry' and answers a specific question. It differentiates from siblings like polymarket_edges by focusing on historical persistence.

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

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

The description implies when to use the tool by contrasting fresh vs old edges, and explains the response structure. However, it does not explicitly state when not to use it or directly compare to alternative tools.

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

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

Annotations already declare readOnly, idempotent, non-destructive. Description adds warnings about partial basket fills converting arb into unhedged directional position, and returns a verdict (clean/degraded/cannot_fill). 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 long but well-structured with headings for single-market and basket, front-loaded with purpose. Each sentence adds value, though could be slightly tighter. Appropriate for complex tool.

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 lists all return fields: top_of_book, vwap, slippage, shares, max_fillable, verdict, plus basket-specific fields like theoretical_sum, capture_ratio, forced_directional_risk. Covers behavioral and safety aspects thoroughly.

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

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

Schema coverage is 100%, but description adds context: default values, interpretation of size_usd per mode, side auto-detection in basket mode. Enriches parameter understanding 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 checks realizable-vs-theoretical edge against live order book depth. Distinguishes between single-market and basket modes, and explicitly tells when to use (before polymarket_arbitrage or polymarket_edges above ~$500). Sibling differentiation is strong.

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 required parameters (market xor event), provides usage context for single-market and basket modes, and gives specific cues (use before arb signals, above $500). No ambiguity.

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=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds extensive behavioral details: compatibility warnings for non-equivalent bet shapes, temporal alignment checks, and counters for skipped comparisons. No contradiction.

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

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

The description is long but every sentence adds value. It is front-loaded with the core purpose, then details modes, response, and safety fields. Could be slightly more concise, but structure is good.

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 explains the response structure (leg-by-leg prices, spread array, safety fields) and covers edge cases like compatibility warnings and temporal alignment. It is comprehensive.

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

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

Schema coverage is 100%, so each parameter has a description. The description adds context for the two modes but does not add new parameter-level details beyond the schema. It does clarify usage of topic vs explicit tickers, which adds value.

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

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

The description clearly states the tool computes cross-venue spread between Kalshi and Polymarket for the same resolving question, using specific verbs like 'cross-venue spread' and 'auto-fetch'. It distinguishes from sibling tools like polymarket_arbitrage by focusing on two-venue comparison and providing safety warnings.

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 tickers) and when to use each, and warns that most pre-mapped topics return compatibility warnings. However, it does not explicitly contrast with siblings like polymarket_edges 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=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds that the result is JSON and hints at the default limit from the schema. No contradictions, but additional behavioral details (e.g., error handling, rate limits) are missing.

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 states the core purpose; the second enumerates parameters and result format. No redundant words, highly front-loaded.

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

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

Given the complexity (7 parameters, no output schema), the description covers purpose, parameter usage, and result format. It mentions the default limit. Lacks error handling or response schema, but sufficient for a well-annotated read-only tool.

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

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

Schema coverage is 100%, but the description adds value by clarifying that SoQL clauses omit the leading '$' and providing example values for 'where' and 'select'. This goes beyond the schema descriptions and aids correct invocation.

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

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

The description clearly specifies the action ('run a Socrata SoQL query'), the target data source ('Howard County Open Data dataset'), and the required parameter ('by resource_id'). It differentiates from sibling tools like 'datasets' (which lists resources) by focusing on direct querying.

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

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

The description explicitly states the supported SoQL clauses and parameters, guiding the agent on how to filter, select, group, order, and paginate. It does not explicitly mention when not to use the tool or alternatives, but the context is clear.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false, so description adds value by explaining the practical meaning (retrieve, not modify) and listing behavior when key omitted. No contradictions.

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

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

Three sentences with no fluff: first defines core function, second gives use case, third explains scope and pairing. Well-structured and front-loaded.

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

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

Description lacks details on return format (e.g., what does it return for a single key vs. listing all keys?). Though annotations cover safety and idempotency, the absence of output schema makes this a moderate gap.

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

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

Schema coverage is 100% with a description for the only parameter 'key'. Description adds context beyond schema: examples of usage and clarification that omitting key lists all, plus scoping and pairing info.

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

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

Description clearly states the tool retrieves a saved value by key or lists all keys when omitted. It specifies the verb (retrieve/list) and resource (saved memory), and distinguishes from sibling tools like remember and forget.

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

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

Description provides explicit use cases (look up user's target ticker, address, research notes) and explains scoping by identifier. It implicitly says when to use (retrieval) and pairs with remember/forget, though does not explicitly state when not to use.

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

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

Annotations already indicate readOnlyHint=true and idempotentHint=true, but the description adds context about the mark_read parameter modifying read status for subsequent calls. This transparency about stateful behavior beyond the annotation's read-only implication is valuable, though not contradictory.

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

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

The description is concise (4 sentences), front-loaded with the core purpose, and each sentence adds meaningful detail without redundancy. No fluff or unnecessary words.

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

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

Given no output schema, the description adequately covers return fields, filtering, mark_read behavior, and provides an alternative access method. It also mentions polling compatibility, making it nearly complete for this tool's complexity.

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

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

With 100% schema description coverage, the description still adds value by explaining the mark_read parameter's effect on feed state and clarifying the use of 'since' as an ISO timestamp. This enriches the schema's basic property 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 'Pull fired events from your subscription feed,' specifying a verb ('pull') and resource ('fired events from subscription feed'). It details return fields (source, citation_uri, raw payload) and filtering options, distinguishing it from sibling tools like 'list_subscriptions' by focusing on alert events.

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

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

The description provides guidance on polling ('Polls work fine') and notes an alternative HTTP endpoint for scripts/dashboards, but does not explicitly contrast with sibling tools. However, it clearly implies this is the tool for alert event retrieval.

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 fan-out behavior to multiple sources, fallback from GDELT to GNews, USPTO soft-failure, and return format. Consistent 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?

Single paragraph front-loads purpose with examples, then covers sources, parameters, and return structure concisely. 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?

Despite no output schema, the description explains the return format (changes[], total_changes, URIs). Addresses sources, limitations (USPTO), and comparison with sibling. Highly complete for a complex tool.

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

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

Schema coverage is 100%, and the description adds usage examples for 'since' (ISO/relative), explains 'value' accepts ticker or CIK, and provides typical monitoring guidance ('30d' or '1m').

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

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

The description starts with user query examples and clearly states that the tool returns a change feed for a company in a time window. It lists the data sources and distinguishes itself from the sibling tool '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?

Explicitly tells when to use this tool versus 'entity_profile' and provides input format guidance. Lacks explicit exclusions for other siblings, but the main alternative is covered.

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

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

Adds context beyond annotations: scoping by identifier, persistence duration (authenticated vs. anonymous), and the key-value storage model. 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?

Four concise sentences, front-loaded with main purpose, no redundant or unnecessary 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 tool with annotations, the description fully covers behavior, usage, and related tools. No output schema needed.

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

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

Schema coverage is 100% with clear parameter descriptions. The description adds example keys but does not provide substantially new semantic information 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 specifies the action ('Save data the agent will need to reuse later') and the resource ('key-value pair'). It clearly distinguishes from sibling tools like 'recall' and 'forget', and provides concrete examples of what to store.

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

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

Explicitly states when to use ('Use when you discover something worth carrying forward') and lists companion tools ('Pair with recall to retrieve later, forget to delete'), offering clear guidance on alternatives.

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

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

Annotations already indicate readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, so the safety profile is clear. The description adds valuable behavioral context: each call cascades through several lookup endpoints internally, replacing 2-3 manual lookups. This goes beyond annotations but could mention any potential limitations or 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 moderately concise but includes repetitive elements (e.g., listing supported types in both the header and within the description). It front-loads examples and usage, which is good, but could be tightened by removing 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 lack of an output schema, the description thoroughly explains the return values for each entity type, including specific identifiers (ticker, CIK, RxCUI) and citation URIs. It also mentions auto-disambiguation and cascading lookups. This provides a complete understanding for an AI agent to use the tool effectively.

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

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

The input schema covers both parameters with descriptions and an enum for 'type'. The description adds examples and clarifies auto-disambiguation for company names (accepts ticker, CIK, or name) and explains the output components (ticker+CIK+Rx norm URI). 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 specifies the tool's purpose: resolving user-spoken names to canonical identifiers. It provides concrete examples ('ticker for...', 'find the CIK for...') and explicitly distinguishes itself by stating 'Use FIRST whenever you have a name but need an ID.' This is highly specific and differentiates it from sibling tools like compare_entities or entity_profile.

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

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

The description gives explicit usage guidance: 'Use FIRST whenever you have a name but need an ID.' It also provides example queries for each supported type. However, it does not explicitly state when not to use or mention alternatives, though the context makes it clear that this is the primary lookup tool for identifiers.

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 and idempotent behavior. The description adds that it probes entities using ai_visibility_check, ranks by score, and returns a ranked list with score, confidence, and signal density, providing useful behavioral context beyond annotations.

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

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

The description is two sentences, front-loaded with the main action, and every sentence adds value with no wasted words.

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

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

Given no output schema, the description adequately explains return values (ranked list with score, confidence, signal density). It does not cover error cases but is sufficient for the tool's purpose.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds minor value by hinting that the first entity should be the subject, but does not elaborate on other parameter semantics 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 tool compares AI visibility across multiple entities side-by-side using ai_visibility_check, and distinguishes from sibling tools like ai_visibility_check (single entity) and compare_entities (generic comparison).

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

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

The description provides a clear use case ('competitive AI-marketing audits') and implies the tool is for comparing multiple entities. It does not explicitly state when not to use it, but the context is sufficient given the sibling tools.

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

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

Adds beyond annotations: mentions partial failures, bundlephobia latency (5-30s), graceful degradation with sources_failed, and details the return summary block. No contradiction.

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

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

Informative and well-structured with front-loaded main purpose. Slightly lengthy but each sentence adds value.

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

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

For a tool with no output schema but complex multi-source behavior, the description adequately explains return format (summary, advisories, links, alternative versions) and edge cases (partial failures).

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 3. Description adds minimal value: mentions scoped package acceptance and default version, but schema already implies these.

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

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

Clearly states it's a composite check for npm packages covering license, advisories, bundle size, etc. Distinguishes itself from siblings like 'scan_competitor_ai_presence' and 'deps.dev:version'.

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

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

Explicitly instructs when to use ('is X safe / popular / small') and when not to use (NPM only, other ecosystems via deps.dev:version directly).

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

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

Annotations already declare readOnlyHint, idempotentHint, and no destructiveness. The description adds valuable behavioral details: cap at 200K chars with truncation flag, embeddings model, windowing, and offset for verbatim quote verification. 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 thorough but not overly verbose. Every sentence provides distinct value, though the implementation details (BGE-base-en, 500-char windows) could slightly increase length. Still 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 no output schema, the description clearly explains the return format: top-N passages with character offsets and similarity scores. It covers constraints, pairing, and usage context comprehensively for a 3-parameter tool.

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

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

Schema coverage is 100%, so baseline is 3. The description adds context: 'Pass the text you already pulled', natural-language query examples, and clarifies the max char limit for text. This goes beyond the schema's basic descriptions.

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

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

The description clearly states 'Semantic search INSIDE a fetched record' with specific verb and resource. It distinguishes from sibling tools by mentioning pairing with ask_pipeworx_grounded and emphasizing that it operates on already-fetched text.

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

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

Explicitly says 'Use when the record is too big to cram into the prompt' and 'Pairs with ask_pipeworx_grounded', providing both when-to-use and alternatives.

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

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

Adds substantial behavioral context beyond annotations: OAuth requirement, subscription creation idempotency implied, delivery limits (SMS cap, webhook auto-disable), and HMAC signing details. 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?

Dense but well-structured, front-loads purpose and key requirement. Slightly long, but each sentence adds value given tool 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?

Covers all key aspects: purpose, prerequisites, types, delivery options, return value, and constraints. Adequate for a creation tool with good annotations and 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?

Despite 100% schema coverage, description enriches each parameter with examples, constraints, and usage notes (e.g., sec_8k items, delivery verification, webhook secret). Adds meaning beyond schema.

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

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

Description clearly states verb (Create), resource (proactive monitoring subscription to live-data event stream), and outcome (returns subscription id). Distinguishes from sibling tools like list_subscriptions and unsubscribe.

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

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

Provides explicit prerequisite (Pipeworx OAuth account), lists supported types with examples, and delivery constraints. Does not explicitly contrast with alternatives like recent_alerts, but includes enough context for appropriate use.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds valuable behavioral context by detailing the output structure (category-bucketed examples with tool+argument shapes) and the guidance on using it as a learning resource. 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 relatively long but well-structured, with a clear front-loaded purpose statement followed by bullet-like enumeration of categories. Every sentence adds value; minimal redundancies. Could be slightly more concise but effective.

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

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

Given that there is no output schema, the description fully explains the return value: category-bucketed example questions with exact tool+argument shapes. It also explains the single optional parameter thoroughly. The tool is simple, and the description leaves no gaps.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds extra meaning by listing possible topic values (finance, pharma, etc.) and explaining the effect of omitting versus passing the parameter, which goes beyond the schema.

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

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

The description clearly states the tool's purpose as the onboarding entry point for an agent that just connected, returning category-bucketed example questions with exact tool+argument shapes. It distinguishes itself from siblings like 'discover_tools' by explicitly stating 'Use this FIRST when you do not yet know what Pipeworx can do for you'.

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

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

The description provides explicit usage guidance: 'Use this FIRST' and specifies when to omit vs. pass the 'topic' argument. It mentions learning to call meta-tools, but does not exclude other sibling tools explicitly. However, the context is clear.

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

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

The description adds important behavioral context beyond annotations: deactivation (not deletion) and availability of historical events via recent_alerts. 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?

Two efficient sentences, front-loaded with purpose and constraint, no waste.

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

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

Given the simple one-parameter tool and comprehensive annotations, the description fully covers behavioral context (ownership, deactivation, historical availability).

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

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

Schema description coverage is 100%, and the description adds minimal extra meaning beyond repeating 'by id'. Adequate but not enhanced.

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

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

The description clearly states the action ('Cancel a subscription by id') and resource ('subscription'), distinguishing it from siblings 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?

The description provides a clear usage constraint ('Ownership is enforced — you can only cancel your own subscriptions'), but does not explicitly mention when not to use or alternative tools.

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

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

Annotations already mark the tool as read-only, idempotent, and non-destructive. The description adds beyond that: it returns a verdict (with specific types like confirmed, refuted, etc.), an extracted structured form, actual value with a citation, and a percent delta. It also discloses the data source (SEC EDGAR + XBRL) and notes that v1 supports only company-financial claims. A minor omission is no discussion of error cases or rate limits.

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

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

The description is fairly long but well-organized. The first line lists example user queries, followed by a clear usage statement, scope, return values, and efficiency note. It could be slightly tightened (e.g., the list of examples is somewhat redundant), but overall it's informative and structured logically.

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

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

With no output schema, the description explains the return structure in plain language (verdict types, extracted form, actual value, citation, delta). The one parameter is fully covered by both schema and description. Annotations are present and consistent. The description provides all necessary context for an agent to decide when to use this tool and what to expect.

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 'claim' has a schema description that says 'Natural-language factual claim'. The tool description expands on this with multiple examples (e.g., 'Apple's FY2024 revenue was $400 billion') and clarifies that it should be a natural-language claim. This adds meaning beyond the schema.

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

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

The description starts with natural-language examples like 'Is it true that…' and 'fact check', then clearly states the tool validates claims against authoritative sources. It distinguishes itself from sibling tools such as ask_pipeworx and deep_research by focusing on factual verification of company-financial claims.

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

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

The description explicitly states 'Use whenever the agent needs to check whether something a user said is factually correct.' It also notes the scope (company-financial claims for public US companies) and provides an efficiency comparison, saying it 'replaces 4–6 sequential calls.' This gives clear when-to-use and when-not-to-use guidance.

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