Data Govt Nz

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds value by detailing the probing process, default model, API key handling, and return structure (per-model and combined). No contradictions.

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

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

The description is concise (4 sentences) and front-loaded with the tool's primary purpose. Every sentence adds value, with no redundant or vague 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 tool with no output schema, the description adequately describes the return format (per-model score, confidence, signals, raw_response, combined). Combined with rich annotations and schema descriptions, it covers usage, parameters, models, and use cases comprehensively.

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

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

All parameters have schema descriptions (100% coverage). The description enriches understanding by noting default models for 'models', BYO key requirement for '_apiKey', and disambiguation purpose for 'context', going beyond schema alone.

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

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

The description clearly states the tool probes LLMs for knowledge about an entity and returns a visibility score (0-100) per model. It distinguishes from sibling tools like compare_entities or entity_profile by specifying AI-marketing audits, pre-launch checks, and competitive monitoring.

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

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

The description provides clear usage context (AI-marketing audits, etc.) and explains when to use the _apiKey parameter for Anthropic models. However, it does not explicitly state when not to use the tool or suggest 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 readOnlyHint, openWorldHint, idempotentHint true and destructiveHint false, covering safety. The description adds behavioral context: 'returns the structured answer with stable pipeworx:// citation URIs' and mentions routing to many tools. While it doesn't contradict annotations, it doesn't disclose additional behavioral traits beyond what annotations provide, just adds some operational context.

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

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

The description is a single paragraph that efficiently conveys the tool's advantage and use cases. It is front-loaded with the key 'PREFER OVER WEB SEARCH' and provides concrete examples. A bit long, but each sentence adds value, making it well-structured and clear.

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

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

Given the tool's complexity (routing to many sources) and no output schema, the description explains that it returns structured answers with citation URIs, which gives a reasonable expectation of the output. It also lists diverse data sources. This is fairly complete for a query tool, though more detail on output format would improve 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 each parameter described as 'Alias for question.' The description does not add extra meaning beyond this; it only reiterates that the tool routes questions. Since schema already describes the parameters adequately, the description adds minimal value for parameter semantics.

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

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

The description clearly states the tool's purpose: 'PREFER OVER WEB SEARCH for questions about current or historical data' and that it 'routes the question to the right one of 3,745 tools across 884 verified sources.' It specifies the verb 'ask' and resource 'Pipeworx', and distinguishes from web search, 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?

The description provides explicit guidance: 'PREFER OVER WEB SEARCH' and lists specific use cases (SEC filings, FDA data, etc.) and example questions. It also states to use whenever the user asks factual questions like 'what is', 'look up', 'find', etc., and even when web search could answer it. This clear when-to-use directive strongly differentiates it from 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. The description adds significant behavioral detail: costs one extra LLM call, returns specific fields like refusal_reason with enumerated reasons ('not_in_source', 'no_tool_match', etc.). 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?

Description is a single paragraph that efficiently conveys purpose, behavior, usage, and return format. Every sentence adds value, though slightly more structured bullet points could improve scannability.

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 comprehensive annotations and schema, the description fully covers return format (including evidence, confidence, source), explicit refusal reasons, cost trade-off, and comparison to sibling. An AI agent has all necessary information to decide when to invoke 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?

Schema coverage is 100% with detailed descriptions for each parameter alias. The description does not add meaningful additional semantics beyond restating that it 'fills arguments' and the aliases are accepted. Baseline of 3 is appropriate since schema already documents parameters completely.

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, specifying it extracts answers only from tool results and returns structured output with evidence or refusal. It explicitly distinguishes itself from the sibling 'ask_pipeworx' by noting the extra LLM call and preference for casual lookups.

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

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

The description provides explicit guidance on when to use: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts' with concrete examples (financial verdicts, legal claims, medical lookups, public statements). It also advises preferring ask_pipeworx for casual lookups, establishing clear usage boundaries.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, no destructiveness. The description adds extensive behavioral details: resolution process, classification, fan-out, response shapes, resolver contract, parent event extractor, news fields, safety short-circuits, closed market handling, wide spread warnings, and resolution-rule risk. No contradiction with annotations.

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

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

The description is long but well-structured with clear sections (classifiers, fan-out examples, response shapes, safety, etc.). Every sentence provides value, so it earns its length. However, some redundancy could be trimmed without loss of meaning.

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

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

Given the tool's complexity (3 parameters, rich annotations, no output schema but detailed response explanation), the description covers all necessary aspects: input formats, processing steps, output fields, edge cases (low confidence, closed markets, wide spreads), safety mechanisms, and resolution rules. It is fully complete for an AI agent to use correctly.

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

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

Schema coverage is 100% with descriptions for all three parameters. The description adds value beyond schema: for 'market' it explains three input formats (slug, URL, question text) and mentions the resolver; for 'depth' it clarifies quick vs thorough; for 'include_raw' it explains impact on response size. Each parameter's meaning is enriched.

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

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

The description clearly states the tool's purpose: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies the resource (Polymarket bet) and action (research by data pull), distinguishing it from sibling tools like polymarket_edges or polymarket_arbitrage that focus on specific aspects.

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

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

Explicit use cases are provided: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' This gives clear context. However, it does not explicitly state when not to use the tool, though the sibling list hints at 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?

The description discloses detailed behavioral traits beyond annotations: it pulls specific financial data from SEC EDGAR/XBRL, handles off-calendar fiscal years, sorts results by primary metric, and returns citation URIs. Annotations already indicate safe read-only behavior, and the description enriches with concrete data sources and handling logic.

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 patterns. It is efficient, with no wasted words, and every sentence adds value. It could be slightly more structured (e.g., separate sections for company vs drug), but overall it is concise and clear.

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 of two entity types with different data sources, the description is remarkably complete. It explains what data is pulled (financials for companies, adverse events for drugs), how off-calendar fiscal years are handled, sorting behavior, and output format (paired data + URIs). Without an output schema, 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 coverage is 100% with both parameters described. The description adds meaning by providing concrete examples (tickers/CIKs for company, drug names), specifying count limits (2–5), and explaining that results are sorted by primary metric. This goes beyond the schema's basic descriptions.

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

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

The description clearly states the tool performs side-by-side comparison of 2–5 companies or drugs in a single parallel call. It specifies the resource (entities) and action (compare), and distinguishes it from sequential lookups via sibling tools like entity_profile.

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

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

The description provides strong positive guidance: 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.' It gives example queries and explains when to use for company vs drug. It does not explicitly exclude scenarios, but the context is clear.

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

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

Beyond annotations (readOnly, openWorld, idempotent), the description discloses the decomposition process, parallel execution, return format (evidences, confidence, gaps), and prerequisites (Pipeworx account, paid plan for thorough depth). No contradiction with annotations.

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

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

The description is informative but not overly verbose. Each sentence adds value: core function, process, return format, usage guidance, and requirements. Well-structured with front-loaded key information.

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

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

Given the tool's complexity and no output schema, the description thoroughly covers what the tool does, how it works, what it returns (structured findings packet with citations), when to use it, prerequisites, and expected latency. It is self-sufficient for an agent to understand and invoke correctly.

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

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

Schema coverage is 100%, baseline 3. Description adds value by explaining that depth controls number of facets and that 'thorough' requires a paid plan, and reinforces that the question is in natural language and broad questions are acceptable.

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

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

The description clearly states the tool performs grounded multi-source research by decomposing questions, routing to parallel tools, and returning structured findings with citations. It distinguishes itself from sibling ask_pipeworx by specifying usage for broad/multi-part questions.

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

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

Explicitly advises using for broad or multi-part questions and provides examples. It also directs to use ask_pipeworx for single lookups, offering a clear alternative.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true. The description adds valuable behavioral context: 'Returns the top-N most relevant tools with names, descriptions, and full input schemas (with curated examples) — each result is ready to call directly, no second schema lookup needed.' This goes beyond annotations by explaining output format and immediate usability.

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

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

The description is a single paragraph that front-loads the purpose and usage. It is relatively concise and each sentence adds value, though it could be slightly more structured (e.g., separating usage from output details). No 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 that the tool has no output schema and 100% schema coverage, the description provides enough context: it explains what is returned (top-N tools with schemas) and that results are ready to call. It does not detail pagination or error handling, but these are reasonable gaps. The tool's meta-purpose is well-covered.

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

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

Schema coverage is 100%, so baseline is 3. The description mentions 'query' and provides examples of valid queries (e.g., 'analyze housing market trends'), but adds minimal additional meaning beyond what the schema already provides (examples in schema). It does not elaborate on the limit parameter beyond its schema description.

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

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

The description clearly states the tool's purpose: 'Find tools by describing the data or task.' It lists specific domains and distinguishes it from sibling tools by explaining it returns tool definitions ready to call. It avoids tautology and provides a specific verb-resource combination.

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

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

The description explicitly says when to use: 'Use when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST when you have many tools available.' It doesn't explicitly state when not to use or list alternatives, but the context is clear enough given the meta-tool nature.

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

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

Discloses fan-out across multiple sources, return fields (with specific data like CIK, filings with URIs, fundamentals sorted), and known limitation (USPTO soft-fail May 2025). Annotations already declare read-only, idempotent, non-destructive; description adds valuable 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?

Description is detailed but somewhat verbose; repeats examples and some schema info (e.g., zero-padded CIK). Could be tightened while retaining value.

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

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

No output schema, so description compensates by listing return fields and sources. Includes caveats (patent sunset). Rich annotations reduce burden further. Complete enough for this 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 100% with clear descriptions; description adds extra nuance: examples, forbidden name inputs, recommendation to use resolve_entity. Baseline 3 with meaningful enrichment.

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

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

Description uses specific verb ('profile'), resource ('US public company'), and scope ('full cross-source') with example queries. Clearly distinguishes from sibling tools like resolve_entity (name resolution) and compare_entities (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?

Explicitly states 'ALWAYS PREFER over chaining single-pack lookups when holistic view needed' and directs to use resolve_entity for name-only inputs. Provides clear context of when and 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 convey destructive and idempotent hints; description adds 'clear sensitive data' but minimal additional behavioral context.

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

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

Two concise sentences, front-loaded with purpose and usage, no wasted words.

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

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

Complete for a simple tool: one param, no output schema, annotations present, and description covers when/why to use.

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

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

Single parameter with clear schema description; description adds no further meaning beyond the schema.

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

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

The description clearly states the tool deletes a stored memory by key, distinguishing it from siblings like 'remember' and 'recall'.

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

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

Explicitly says when to use (stale context, task done, clear sensitive data) and pairs with related tools.

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

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

The description discloses the process: fetching the page, extracting data, and emitting markdown. Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the description adds behavioral detail without contradiction.

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

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

The description is two sentences with no wasted words, front-loading the primary purpose and immediately adding use cases.

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 adequately explains the process and output. Minor gaps (error handling, large site limits) exist, but overall 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?

The schema covers both parameters with descriptions. The narrative adds meaning by explaining that the URL is fetched and max_links controls entries, going beyond the schema's text.

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

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

The description clearly states the tool generates a production-ready llms.txt file for any URL, specifying the verb (generate), resource (llms.txt file), and target (any URL). It is distinct from sibling tools like ai_visibility_check.

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

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

The description lists specific use cases (getting a client's site indexed, drafting your own, auditing competitors), providing clear context. It does not explicitly mention when not to use or alternatives, but the given context is adequate.

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

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

Annotations already indicate readOnly, openWorld, idempotent, and non-destructive behavior. The description adds no additional behavioral context, failing to mention pagination or output structure.

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?

While very short, the description is under-specified and does not effectively convey purpose, sacrificing clarity for brevity.

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

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

Despite having an output schema and annotations, the description is extremely incomplete, offering no information about output, pagination, or how it relates to sibling tools.

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

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

The description does not explain any of the three parameters (limit, offset, all_fields), and schema description coverage is 0%, so no value is added.

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 'Groups/categories.' is vague and lacks a verb. It does not clearly state that the tool lists groups, nor does it distinguish from sibling tools like group_show.

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

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

No guidance is provided on when to use this tool versus alternatives such as group_show or other list 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 declare readOnlyHint=true, destructiveHint=false, which cover safety. However, the description adds no behavioral context beyond what annotations provide (e.g., that it returns group details, or that include_datasets affects response). Bar is lower due to annotations, but description should still add 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?

At only two words, the description is under-specified rather than concise. It lacks structure and substance, failing to earn its place by providing useful information.

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

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

Given the tool has 2 parameters, an output schema, and sibling tools, the description is completely inadequate. It does not explain what the tool does, what it returns, or how parameters affect behavior.

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

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

With 0% schema description coverage, the description must explain parameters. It does not mention 'id' or 'include_datasets' at all. The schema's examples provide some hints but the description should reinforce meanings.

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 'Single group.' is almost tautological with the title 'Group Show'. It does not specify a verb (e.g., retrieve, show) nor distinguishes from sibling 'group_list'. It provides minimal clarity about the tool's function.

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

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

No guidance is provided on when to use this tool versus alternatives like 'group_list' or 'group_show' siblings. The description lacks any contextual cues for appropriate usage.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds that it returns active subscriptions by default and lists specific fields, providing useful context beyond what annotations offer.

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

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

Two efficient sentences: first states purpose and return fields, second gives usage guidance. No unnecessary words.

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

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

For a simple list tool with one optional parameter and no output schema, the description covers purpose, return fields, and usage. It is complete and helps the agent understand the tool.

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

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

Schema coverage is 100% with one optional parameter described in the schema. The description does not add additional parameter meaning, 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 states the verb 'List', the resource 'subscriptions', and specifies the return fields (id, type, params, created_at, last_fired_at, fire_count). It distinguishes itself from siblings like subscribe and unsubscribe.

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

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

Explicitly tells when to use: 'before adding more' or 'to find an id to cancel'. Does not mention alternatives, but among siblings there is no other list 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 indicate readOnlyHint=true and destructiveHint=false. The description adds no behavioral context beyond what annotations provide, such as pagination behavior, rate limits, or response structure.

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 extremely terse (two words) but under-specified, not concise in a helpful way. It lacks structure and fails to provide necessary information in an organized manner.

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

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

Given the tool has three parameters, an output schema, and many sibling list tools, the description is incomplete. It omits critical details for selection and correct invocation.

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

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

Schema description coverage is 0% and the tool description does not explain any parameters (limit, offset, all_fields). The agent must rely solely on parameter names and examples, which is insufficient.

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 'Publishing orgs.' is a vague phrase that does not clearly state the action (e.g., list, get) or what 'publishing orgs' specifically means. It lacks specificity and does not distinguish from sibling tools like 'group_list' or 'package_list'.

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

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

No guidance is provided on when to use this tool versus alternatives. There is no mention of context, prerequisites, or when not to use it.

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

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

Annotations already indicate readOnlyHint=true and destructiveHint=false, so safety is clear. However, the description adds no behavioral context beyond what the annotations imply, such as confirming it retrieves a single org's details or any side effects.

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

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

The description is extremely concise (two words) but at the cost of informativeness. While brevity is valued, this lacks essential structure and fails to convey meaningful details.

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

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

Given the tool has 2 parameters, no schema descriptions, and an output schema (not shown in description), the description provides zero contextual completeness. It does not clarify what the endpoint returns, how parameters affect output, or any usage context.

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 0%, and the description does not mention any parameters. The two parameters (id and include_datasets) are left completely unexplained, leaving the agent to guess their purpose and constraints.

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 'Single org.' merely restates the tool name with minimal elaboration. It does not specify the action (e.g., retrieve or show) or what aspect of the organization is returned, making it a near-tautology.

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

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

No guidance is provided on when to use this tool versus sibling tools like organization_list or group_show. There are no scenarios, prerequisites, or exclusion criteria mentioned.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, making the tool's safety and idempotency clear. The description adds no extra behavioral context (e.g., pagination, response format), which is acceptable given the annotations cover the main risks.

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 extremely short (4 words), which is concise but not optimally structured. It front-loads the purpose but omits critical details about parameters and usage, making it less helpful than it could be.

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 presence of an output schema and simple parameters, the tool is not complex. However, the description should at least hint at pagination (limit/offset) to be complete. It falls short of providing sufficient context for correct invocation.

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

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

With 0% schema description coverage, the description must compensate by explaining the two parameters (limit, offset). However, it fails to mention them at all, leaving agents without semantic understanding beyond the schema types.

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 'List dataset names' clearly identifies the action (list) and resource (dataset names), matching the tool name 'package_list'. However, it is vague about scope (all datasets? filtered?), and the name suggests 'packages' rather than 'datasets', which may cause minor confusion.

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

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

No guidance is provided on when to use this tool versus alternatives like 'package_search' or 'recently_changed_packages'. There is no mention of context, prerequisites, or exclusions, so agents lack direction for selection.

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

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

Annotations already indicate read-only, open-world, idempotent, non-destructive behavior. The description adds only 'full-text + faceted', which hints at search types but doesn't disclose pagination, result limits, or other behavioral traits beyond what annotations convey.

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?

At only five words, the description is excessively terse. While conciseness is valued, it omits critical information that should be present for a complex search tool, making it under-specified rather than efficiently concise.

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

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

Despite having an output schema, the description fails to explain the search functionality adequately. With 6 undocumented parameters and no usage context, the description is incomplete for a tool of this 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?

The input schema covers 6 parameters with 0% description coverage. The description provides no explanation of any parameter, leaving agents without guidance on how to construct queries or interpret fields like 'fq', 'sort', or 'facet_field'.

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 'Full-text + faceted search' clearly indicates the tool performs search with faceting, distinguishing it from list or show tools. However, it doesn't explicitly differentiate from sibling search-like tools like 'search_within' or 'package_list'.

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

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

No guidance is provided on when to use this tool versus alternatives. There is no mention of prerequisites, exclusions, or typical search scenarios.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds no behavioral context beyond these, such as whether results are paginated, cached, or require authentication. 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 a two-word fragment. While short, it is not concise in a helpful sense – it omits essential information and fails to earn its place. A good description would be structured with at least a verb and object.

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

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

Despite having an output schema (unknown content) and simple parameter, the description is wholly inadequate. It does not explain what the tool returns, how to interpret the result, or any edge cases. The agent has no context for 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 0% – the description provides no additional meaning for the required 'id' parameter. The agent must infer that 'id' identifies a dataset, but the description does not clarify the format or source of valid IDs.

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 'Single dataset.' is a tautology, merely restating the resource type without specifying what the tool does. It does not convey that the tool retrieves details of a specific dataset by ID, nor does it differentiate from sibling tools like group_show or resource_show.

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

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

No guidance on when to use this tool versus alternatives. Sibling tools include many 'show' variants (group_show, organization_show, resource_show) but the description offers no context for 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?

The description discloses behavioral traits such as rate limiting (5 per identifier per day), being free and not counting against tool-call quota, and that the team reads digests daily. Annotations provide no such info, so the description fully addresses behavioral transparency.

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

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

The description is a single dense paragraph that front-loads the core purpose. Every sentence adds value, but could be slightly more structured (e.g., bullet points for usage cases). Still efficient and 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 the tool's simplicity (3 parameters, no output schema), the description covers all essential aspects: purpose, usage triggers, rate limits, and guidance on message content. It is complete for practical use.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining the 'type' enum values in detail, providing formatting guidance for 'message' (1-2 sentences, 2000 chars), and clarifying that 'context' is optional. This exceeds the baseline.

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

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

The description clearly states the tool's purpose: sending feedback (bug, feature, data_gap, praise) to the Pipeworx team. It is specific and distinct from sibling tools, none of which are for feedback.

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 when to use: for bugs, missing features, data gaps, or praise. It also provides guidance on what to avoid (don't paste end-user prompt) and mentions rate limits and quota exemption.

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 safety hints. The description adds valuable context: data source (CF analytics-engine), no PII, and caching behavior (5min-1h). No contradictions.

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

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

The description is concise with bullet points, first sentence captures core functionality, 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?

While no output schema exists, the description explains return values (top tools, top packs, total call volume) and caching. Sufficient for agent understanding, though exact format not detailed.

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

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

Schema has 100% coverage with enum description. The description adds further meaning by explaining the effect of windows ('shorter windows surface what's hot right now'), providing extra value.

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

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

The description clearly states the tool returns 'top tools, top packs, and total call volume' and gives specific use cases. It distinguishes itself from siblings as the only trending-related 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?

The description explicitly lists three use cases where this tool is useful. While it doesn't mention when not to use it or compare with alternatives, the context is clear and sufficient.

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

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

Discloses detailed behavior including semantic anchor (Jaccard similarity), partition filter, fill check against live CLOB depth. Annotations indicate read-only, idempotent, non-destructive, and description adds 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?

The description is dense but information-rich, front-loading the requirement. While every sentence adds value, it could be slightly more structured for easier scanning.

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

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

Despite no output schema, the description details the response fields (opportunities[], partition_check, fill_check) and references sibling tool for custom sizing. Annotations cover safety, and description adds comprehensive behavioral context.

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: explains that event is for single-event mode, topic for cross-event mode, provides concrete examples, and describes the mode-dependent behavior.

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

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

The description clearly states the tool finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes between event and topic modes, and from sibling tools like polymarket_edges and 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?

Explicitly explains when to use event mode (specific known event) vs topic mode (cross-event scanning). Warns that call with no args fails. Provides example inputs for both modes.

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 rich behavioral context: caching policy (1h at KV level), detailed explanation of edge calculations (e.g., slippage, Kelly sizing, 24h-move warnings), and thorough disclosure of how each segment works and what diagnostics are included. No contradiction with annotations.

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

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

The description is thorough but overly long and dense, with technical details on model families and edge formulas. It front-loads the purpose but then becomes verbose. While structured into segments and knobs, it could be more concise by condensing some explanatory text. Every sentence earns its place, but the overall length reduces readability.

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

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

Given no output schema, the description does a good job explaining the response structure (by_segment, fed_candidates, diagnostics) and fields (edge_pp_net, kelly_fraction, market.liquidity, etc.). It also covers the tradeable-edge knobs and filtering logic. However, an explicit output schema or example would further improve completeness.

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

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

Schema coverage is 100%, but the description adds significant beyond-schema value for all 9 parameters. For example, min_kelly explains it skips 'opportunities that are too small to bet sensibly', slippage_pp discusses Polymarket's fee structure and depth, and min_liquidity warns about walking the book. These enrich the schema definitions considerably.

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

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

The description clearly states the tool's purpose: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It is built for daily discovery and distinguishes the three model families. However, it does not explicitly differentiate from sibling tools like polymarket_arbitrage, which would clarify when to use this one over others.

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 usage context ('what should I bet on today') and provides detailed guidance on the response segments and filtering knobs. It mentions that Fed bets surface but are excluded from ranking. However, it lacks explicit when-not-to-use guidance or comparisons to alternatives, so agents might not know when to prefer this over 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?

The description discloses key behavioral traits beyond annotations: snapshot TTL (60 days), gaps in data, decay from daily closes (not intraday), and response structure (tracked, expired, snapshot_dates). No contradiction with annotations (which are all non-destructive).

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

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

The description is dense but well-organized: opening purpose, a real-world reasoning example, then detailed response format. Every sentence adds value, though slightly longer than minimal.

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 and moderate complexity (snapshots, time-series), the description covers all key aspects: response fields, edge cases (gaps, TTL, expired opportunities), and data interpretations (median lifespan as competition clock).

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 valuable context: explains 'days' as lookback with default and max, 'window' as snapshot family with default. This meaningfully extends the schema definitions.

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

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

The description clearly states the tool's purpose: 'Edge persistence and decay telemetry... Answers how long has this edge existed and is it shrinking?' It distinguishes from sibling tools like polymarket_edges by focusing on historical persistence and decay, not just current snapshots.

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

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

The description provides context for when to use the tool, e.g., 'a fresh wide edge and a 3-week-old wide edge are different trades.' It implies usage for understanding edge history but does not explicitly state when not to use or list 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, openWorldHint, idempotentHint, and destructiveHint=false. The description builds on this by detailing the behavioral traits: it walks the order-book ladder, returns a verdict (clean/degraded/cannot_fill), and explains that thin books make theoretical overround uncapturable. This adds significant value beyond the annotations without contradicting them.

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

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

The description is well-structured with clear sections for required parameters, single-market, and basket modes. It is dense with information but not verbose; every sentence adds value. However, the length might be slightly heavy for quick scanning, but it earns its 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?

Despite lacking an output schema, the description enumerates all returned fields (top_of_book, vwap_fill_price, slippage_pp, etc.), explains the verdict, and covers edge cases like thin_legs and forced_directional_risk. For a complex tool with two modes, the description is remarkably complete and anticipates agent 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 description coverage is 100%, but the description adds rich semantics: it explains the dual role of size_usd (spend vs. proceeds vs. settlement notional), the auto-detection of side for baskets, and the distinction between market and event parameters. The description deepens understanding beyond the schema definitions.

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

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

The description clearly states the tool performs a 'realizable-vs-theoretical edge check against live CLOB order-book depth.' It explains two distinct modes (single-market and basket) and explicitly distinguishes itself from sibling tools like polymarket_arbitrage and polymarket_edges by directing usage before those tools.

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

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

The description provides explicit usage guidance: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also warns about the risk of partial basket fills converting an arb into an unhedged directional position, giving clear context on when the tool is critical.

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

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

Annotations indicate read-only, idempotent, open-world. Description adds rich behavioral details: compatibility_warning for non-equivalent bet shapes, temporal alignment checks, skipped cross types. No contradiction with annotations. Thoroughly explains edge cases and limitations.

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

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

Description is quite long (multiple paragraphs) but well-structured with front-loaded purpose, then modes, response format, safety fields. Every sentence adds value, but could be tightened slightly without losing clarity.

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

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

Given no output schema, description fully explains response structure (leg-by-leg prices, top_spreads_pp, safety fields). Covers temporal alignment, skipping logic, and when spreads are meaningful. Complete for a complex cross-venue tool.

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

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

Schema coverage is 100% with good descriptions. Tool description adds value by explaining the two modes, providing example values for topic, and clarifying how parameters interact (topic as shortcut, explicit overrides). Enhances understanding beyond schema alone.

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

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

Clearly states it's a cross-venue spread tool between Kalshi and Polymarket for the same resolving question. Distinguishes two modes (topic shortcuts and explicit tickers). Differentiates from siblings like polymarket_arbitrage by focusing on cross-venue comparison.

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

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

Explicitly describes when to use topic mode vs explicit tickers. Warns that most pre-mapped topics return warnings, guiding proper use. Lacks explicit when-not-to-use and alternative sibling tool names, but provides sufficient context for appropriate selection.

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

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

Annotations already cover readOnly, idempotent, non-destructive. Description adds scoping to user identifier and behavior when key is omitted (list all). Does not describe return format, but acceptable given simplicity.

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

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

Two sentences, front-loaded with key action, minimal waste. Each 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 no output schema, description covers behavior, usage context, and pairing with siblings. 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 100% already documents parameter behavior. Description reinforces omit-to-list-all, but adds no new semantic info 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 retrieval by key or listing all keys. Provides concrete examples like ticker, address, research notes. Distinguishes from siblings '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?

Explicitly says when to use: 'to look up context the agent stored earlier' and 'without re-deriving it from scratch'. Mentions pairing with remember and forget. Could be more explicit about when not to use, but context is clear.

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

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

Annotations indicate readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds behavioral context beyond annotations, such as that mark_read flags events as read, affecting subsequent calls, and that the feed is persisted. 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 four sentences, front-loaded with the main action, and every sentence adds essential information without redundancy. It is concise 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 explains return fields (source, citation_uri, raw payload), covers polling behavior, and mentions an alternative access method. It is complete for a read-only retrieval tool.

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

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

Schema coverage is 100% with parameter descriptions. The description adds value by explaining mark_read semantics ('flag returned events read so the next call only shows newer ones') and providing an example filter type ('sec_8k'). This enhances understanding beyond the schema.

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

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

The description explicitly states the tool pulls fired events from a subscription feed, lists the return fields (source, citation_uri, raw event payload), and mentions filtering options. It clearly identifies the tool's function as retrieving recent alerts, distinguishing it from sibling tools like subscribe or 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 advises that polling works fine and provides an alternative HTTP endpoint for scripts/dashboards, indicating appropriate use cases. However, it does not explicitly compare to sibling tools or state 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 declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds significant behavioral context: fans out to multiple sources, GDELT preferred with GNews fallback on rate limits/5xx, USPTO soft-fails until reactivated, and returns structured changes with citation URIs. No contradiction with annotations.

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

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

The description is a single paragraph but very information-dense. It front-loads example queries and covers all key aspects concisely. Could be slightly better structured with bullet points, but every sentence adds value.

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

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

Although there is no output schema, the description details the return structure: changes[] grouped by source, total_changes count, and pipeworx:// citation URIs. For a tool with 3 well-documented parameters and rich annotations, this is complete and sufficient for an agent to understand inputs and 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 description coverage is 100%, so baseline is 3. The description adds value by providing concrete examples for `since` ('7d', '30d', '3m', '1y') and noting that `type` is only 'company'. It also explains the `since` parameter in the context of the time window for each data source.

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

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

The description explicitly states the tool provides a change feed for a company over a recent time window, fanning out to SEC, news, and patents. It gives example queries like 'what's new with X' and distinguishes from sibling tool entity_profile, making the purpose very clear.

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

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

The description includes explicit guidance on when to use this tool versus entity_profile ('Use entity_profile instead when you want the static profile'). It also provides context about when to use relative shorthand vs ISO date and the source fallback behavior.

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

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

Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds no additional behavioral context (e.g., pagination, ordering, time window), so it provides minimal value beyond annotations.

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

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

The description is extremely short (two words) but fails to convey useful information. It is under-specified rather than concisely 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?

Given the presence of an output schema and multiple sibling tools, the description is incomplete. It does not explain what 'recent updates' means, how results are sorted, or any return fields. The tool's behavior is poorly communicated.

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 0% and the description does not mention the 'limit' and 'offset' parameters. The schema lacks descriptions for these properties, so the agent has no guidance on their meaning or usage.

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

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

The description 'Recent updates.' is vague and does not specify that it pertains to packages. The name and title imply packages, but the description lacks resource specificity and does not distinguish from siblings like 'recent_changes' or 'package_list'.

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

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

No guidance is provided on when to use this tool versus alternatives. With many sibling tools for listing packages and changes, the description offers no context for 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?

The description adds detail beyond annotations: key-value pair scoped by identifier, persistent for authenticated users, 24-hour TTL for anonymous sessions. 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 sentences, front-loaded with purpose, no wasted words. Well-structured for quick comprehension.

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

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

Given 2 required params, no output schema, the description fully covers purpose, usage, persistence, and lifecycle (with recall/forget). Complete for an AI agent to use correctly.

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

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

Schema already covers both parameters with descriptions. The description adds concrete examples for key (subject_property, target_ticker) and value (any text), which adds helpful 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 verb 'save' and resource 'data for later reuse', and distinguishes from sibling tools like 'recall' and 'forget'.

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

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

Explicitly says when to use: when discovering something worth carrying forward, and mentions pairing with recall and forget for retrieval/deletion.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, covering safety. The description adds that each call cascades through several lookup endpoints internally, which provides useful behavioral 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 a single dense paragraph with no wasted words. It is front-loaded with query examples, then usage instruction, then detailed type information. Every sentence serves a purpose, maintaining clarity without verbosity.

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 adequately explains return types (ticker, CIK, RxCUI) and citation URIs. Given the internal cascading complexity, the description provides sufficient context for an AI agent to understand inputs and outputs. A score of 5 would require explicit mention of rate limits or error cases.

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: for 'type' it details supported types and their return values (ticker, CIK, etc.), and for 'value' it gives example inputs, mentions auto-disambiguation for companies, and clarifies formats. This goes well beyond the schema's enum and brief descriptions.

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

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

The description clearly states the tool resolves user-spoken names to canonical identifiers with specific examples (e.g., 'What's the ticker for…') and distinguishes itself from siblings by noting it replaces 2-3 manual lookups. It explicitly lists supported entity types and their return values, making the purpose extremely clear.

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

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

The description explicitly says 'Use FIRST whenever you have a name but need an ID,' providing strong guidance on when to use the tool. However, it does not explicitly state when not to use it or mention alternatives among siblings like entity_profile or compare_entities, which would earn a 5.

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 non-destructive behavior. The description adds no behavioral context (e.g., what the response contains or any side effects).

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

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

The description is extremely short but fails to earn its place because it adds no meaningful information. It is underspecified rather than concise.

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

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

Even with an output schema present, the description does not hint at the return structure. For a simple retrieval tool, the description should at least mention the purpose of the id field.

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 0%, and the description does not explain the 'id' parameter. The agent is left to guess what kind of identifier is needed.

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

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

The description 'Single resource.' is a tautology that restates the name without specifying the verb (show/get) or the type of resource. It does not differentiate from sibling tools like entity_profile or package_show.

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

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

No guidance is provided on when to use this tool versus alternatives. The agent is given no context about prerequisites or exclusions.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. Description adds that it probes each entity with ai_visibility_check and returns a ranked list with score, confidence, signal density. No contradictions.

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

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

Two well-structured sentences that front-load purpose and then provide necessary details. 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, the description covers output shape (ranked list with score, confidence, signal density) and process. Complete for the tool's complexity.

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

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

Schema coverage is 100%. Description adds meaning beyond schema: explains first entity is the 'subject', and _apiKey is only needed if 'anthropic' in models.

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, probes with ai_visibility_check, ranks by score, and surfaces most/least recognized. It distinguishes from siblings like ai_visibility_check and compare_entities.

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

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

It explicitly says when to use: 'for competitive AI-marketing audits' and gives an example. While it doesn't explicitly state when not to use, the context is clear and sufficient.

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

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

Discloses important behavioral traits beyond annotations: partial failures degrade gracefully, bundlephobia first measurement can take 5-30s, and sources_failed will list timeouts. Also outlines return structure (summary block, per-advisory detail, links, alternative versions). No contradiction with annotations.

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

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

Description is moderately concise and front-loaded with purpose. While somewhat lengthy, every sentence adds value, explaining the composite nature, data sources, use cases, and behavior. Minor redundancy in listing return fields could be tightened.

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

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

Given the tool's complexity (multiple data sources, error handling), the description covers usage, ecosystem scope, return fields, and partial failure behavior. Lacks detailed response format but lists key fields. Adequate without output schema.

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

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

Schema coverage is 100% and description does not add significant meaning beyond what the schema provides (package name, optional version). The description mentions version default behavior ('latest published version when omitted') but schema already indicates optionality. 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 specific action: a composite check for npm package quality combining deps.dev and bundlephobia data. It distinguishes itself from sibling tools like entity_profile and package_show by positioning as a one-call evaluation for adding packages.

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

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

Provides explicit guidance on when to use: queries about safety, popularity, size, or cost. Also specifies ecosystem limitations (NPM only) and directs PyPI/Maven/Cargo/Go to deps.dev:version directly, clarifying 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?

Adds technical details beyond annotations: BGE-base-en embeddings, cosine, overlapping windows, 200K char cap with truncation flag. 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?

Front-loaded with core function. Each sentence adds value, though some technical details at the end could be slightly condensed.

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 embedding details, char cap, return values (offsets, scores), and pairing with sibling tool. Very complete given no output schema.

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

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

Schema covers 100% with descriptions; description enriches with examples for query and default for limit, adding 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?

Clearly states 'semantic search INSIDE a fetched record' with specific verb and resource. Distinguishes from siblings by mentioning pairing with ask_pipeworx_grounded and saving context.

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 record is too big for prompt, and provides pairing context. Lacks explicit when-not-to-use but implies scope.

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, including authentication requirements, type-specific behaviors, delivery channel constraints (verification, cap, HMAC signing, auto-disable). No contradiction with annotations.

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

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

The description is well-structured and front-loaded, starting with purpose and return, then prerequisites, types with examples, and delivery channels. 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?

The description covers inputs, side effects, and constraints thoroughly but could provide more detail on the response format beyond just the subscription id, given no output schema.

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

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

Schema coverage is 100%, and the description adds substantial value with concrete examples for each type and delivery channel, enhancing understanding beyond the schema descriptions.

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

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

The description clearly states the tool creates a proactive monitoring subscription to a live-data event stream and returns the subscription id. This specific verb+resource phrasing distinguishes it 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?

The description specifies the requirement for a Pipeworx OAuth account and enumerates supported types and delivery channels with constraints. However, it does not explicitly compare with sibling tools to guide when to use this tool versus alternatives.

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

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

Annotations indicate readOnly, openWorld, idempotent, non-destructive. Description adds detail on return shape (category-bucketed examples with exact tool+argument shape), behavior with/without arguments, and topic filtering. No contradictions.

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

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

Description is thorough and well-structured, starting with common queries then explaining output and usage. Could be slightly condensed, but every sentence serves a purpose.

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

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

With no output schema, description adequately explains return type and content. Covers purpose, parameter usage, and when to invoke. Complete for a simple onboarding tool.

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

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

Single parameter 'topic' with schema coverage 100%. Description adds concrete allowed values (finance, pharma, etc.) and clarifies that omitting returns a full spread, adding significant 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's purpose as an onboarding entry point that returns category-bucketed example questions. Distinguishes from siblings like 'ask_pipeworx' and 'discover_tools' by explicitly recommending to use this first to learn what Pipeworx can do and how to call meta-tools.

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

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

Explicitly says when to use (first when unsure of capabilities) and how to optionally focus via topic parameter. Does not provide explicit when-not-to-use or alternatives, but context strongly implies usage for initial exploration.

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

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

Annotations provide readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false, but the description adds no behavioral context beyond what annotations already indicate. It does not disclose any additional traits like filtering behavior or scope.

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 extremely short ('Tag list.'), but it is under-specified rather than concise. It does not convey functional information efficiently.

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

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

Given the tool has 3 parameters, no schema descriptions, and no explanation of the output (though output schema exists), the description is woefully incomplete for an agent to use correctly.

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

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

No parameter descriptions are provided in the schema, and the description does not explain the meaning of query, all_fields, or vocabulary_id. With 0% schema description coverage, the description fails to compensate.

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 is 'Tag list' which is a tautology, restating the tool name without specifying what the tool does or distinguishing it from sibling tools like tag_show.

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

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

No guidance on when to use this tool versus alternatives such as tag_show or other listing tools. The description does not mention any conditions or exclusions.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, but the description adds no behavioral context beyond what annotations already convey. No mention of rate limits, auth needs, or side effects.

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

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

The description is extremely short (two words) but not in a helpful way. It omits critical information, so it is under-specified rather than concise.

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

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

With 0% schema description coverage, 2 parameters, and no param details in the description, the tool is not usable. The output schema helps but doesn't compensate for the lack of input semantics.

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 0%, and the description gives no explanation of the 'id' or 'include_datasets' parameters. The agent is left to guess what these fields mean.

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 'Single tag.' barely adds clarity beyond the tool name and title. It fails to specify the action (e.g., retrieve, display) or the resource context, making it nearly a tautology.

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

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

No guidance is provided on when to use this tool versus siblings like tag_list. The description does not indicate whether this is for fetching details of a single tag vs listing multiple tags.

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 behavioral details beyond annotations: the row is deactivated (not deleted) and historical events remain. This aligns with annotations (idempotentHint, destructiveHint) and 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?

Three concise sentences with no fluff. Each sentence adds essential information: action, ownership, and data persistence.

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

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

Given one parameter, full schema coverage, no output schema, and sufficient annotations, the description fully covers the tool's purpose, constraints, and effects. No gaps.

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

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

Schema coverage is 100%, and the description adds that the id is 'returned by subscribe', which clarifies the parameter's source and context beyond the schema's description.

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

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

The description clearly states the verb 'Cancel' and the resource 'subscription by id', and adds ownership enforcement. This distinguishes 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 specifies ownership enforcement, implying when to use (own subscriptions) and when not to (others' subscriptions). It does not explicitly name alternatives but 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 declare readOnlyHint and idempotentHint. Description adds domain specificity, data source (SEC EDGAR+XBRL), and return structure (verdict, actual value, citation, delta). No contradictions.

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

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

Somewhat verbose with many example phrasings, but front-loaded with purpose. Could be more concise while retaining key information.

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

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

Given single parameter and no output schema, description fully explains behavior, return values, and usage context. Complete for the tool's complexity.

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

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

Schema coverage is 100%, but description enhances the 'claim' parameter with examples and natural-language context, making its usage clearer.

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 fact-checking of natural-language claims against authoritative sources, specifically for company-financial claims using SEC EDGAR+XBRL. It distinguishes from siblings by noting it replaces multiple sequential calls.

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

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

Explicitly says to use when checking factual correctness of user statements, and specifies the domain (company-financial claims). Lacks explicit exclusions but provides clear context.

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