Flickr Public

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

Annotations indicate read-only, idempotent, non-destructive behavior. The description adds that passing _apiKey triggers Anthropic calls paid by the user, and details the return structure. No contradictions with annotations.

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

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

The description is two sentences plus a brief list of return fields. It is front-loaded with the main action and contains no fluff.

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

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

The description covers all four parameters, use cases, and return format despite no output schema. It lacks error handling or rate limit notes but provides sufficient context for typical use.

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

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

Schema coverage is 100% with clear parameter descriptions. The tool description adds value by clarifying the default model and the payment responsibility for Anthropic calls, which is 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 probes LLMs for knowledge about an entity and scores visibility (0-100). It mentions the default model and optional Anthropic probing, clearly distinguishing the tool's function from siblings like scan_competitor_ai_presence.

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

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

The description lists use cases (AI-marketing audits, pre-launch brand checks, competitive monitoring) and explains when the _apiKey is needed. However, it does not explicitly state when not to use the tool or name alternative sibling tools.

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

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

Annotations already indicate readOnlyHint=true, openWorldHint=true, destructiveHint=false. The description adds context about filling arguments, returning stable pipeworx:// citation URIs, and the tool's extensive backend, which enhances transparency beyond annotations.

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

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

The description is somewhat lengthy but every sentence adds value, starting with a strong usage preference. It is well-structured and front-loaded. Minor verbosity but not excessive.

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

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

Given the tool has only one parameter and no output schema, the description is highly complete. It explains the tool's purpose, usage scope, behavior (routing, citations), and provides concrete examples, covering all necessary context for an AI agent.

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

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

Schema coverage is 100% with a single 'question' parameter described as 'Your question or request in natural language'. The description adds value by specifying the types of questions and providing examples, which helps the agent understand the expected input format.

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 routes questions to appropriate tools from over 1,423 tools across 392+ sources, returning structured answers with citations. It lists specific data types (SEC filings, FDA drug data, etc.) and provides examples, distinguishing it from web search.

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

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

The description explicitly prefers 'ask_pipeworx' over web search for factual, authoritative data. It gives detailed when-to-use guidance with examples like 'current US unemployment rate' and 'Apple's latest 10-K', and implies the tool handles structured data queries.

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, non-destructive. The description adds behavioral context: fan-out logic based on classification, default depth 'thorough', and returns a comparison. It does not contradict annotations. Could mention rate limits or external data sources, but overall adds value beyond structured fields.

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

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

A single paragraph, reasonably concise. First sentence front-loads the main action. Includes some promotional language ('core demo product', 'convert better') that is not strictly necessary but adds context. Could be slightly more structured, but overall effective.

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

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

Despite no output schema, the description clearly explains what is returned: 'evidence packet plus a simple market-vs-model comparison'. All inputs and the overall process are covered. The tool is simple (2 params, no nested objects), and the description provides enough context for an agent to invoke it correctly.

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

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

Schema has 100% coverage with clear descriptions. The description enriches both parameters: for 'market', it gives three concrete input formats; for 'depth', it explains the difference between 'quick' and 'thorough'. It also adds context that the tool fans out to appropriate packs, which is not in the schema.

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

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

The description clearly states the tool's purpose: research a Polymarket bet via Pipeworx data. It specifies inputs (slug, URL, question text), actions (resolve, classify, fan out), and output (evidence packet + comparison). It distinguishes itself from siblings by positioning as the core demo product that saves agents from discovering packs manually.

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: 'should I bet on X?', 'what does the data say?', 'is there edge?'. It explains its advantage over alternative approaches. Lacks explicit when-not-to-use or alternative tools, but the given context is sufficient for an agent to decide when to invoke.

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

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

Annotations already provide readOnlyHint, openWorldHint, and destructiveHint, so the description's additional context is minimal. It adds that uploads are public and scoped to a group, but lacks details on pagination, rate limits, or data freshness.

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

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

The description is very concise with no wasted words. It front-loads the key action and resource. However, it sacrifices informativeness 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?

For a simple tool with two parameters and no output schema, the description is incomplete. It fails to explain return values, default limit behavior, or how results are ordered. The agent is left with many unknowns.

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 50% (only group_id described). The description does not clarify the 'limit' parameter, its default, or permissible values. It adds no new meaning beyond the schema for group_id.

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 'Public uploads in one group' conveys the core functionality (listing public uploads) and identifies the resource (group), distinguishing it from sibling 'by_user'. However, it could be more explicit with a verb like '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 on when to use this tool versus alternatives such as 'by_user'. The description does not specify prerequisites or context, leaving the agent to infer 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 and destructiveHint=false. The description adds 'public', implying no authentication needed but adds little else. No behavioral details (e.g., pagination, rate limits) are disclosed 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 concise (5 words) but is a fragment rather than a complete sentence. While it front-loads the key information, it sacrifices clarity and completeness.

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 and no output schema, the description is insufficient. It does not explain the limit parameter, return format, or any edge cases, leaving significant gaps for an agent.

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

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

Schema coverage is 50%; user_id has a helpful description (NSID or screenname), but limit has no description. The tool description does not elaborate on parameters, so it partially compensates for the missing 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 'Public uploads from one user' clearly states the resource (uploads) and the user scope, distinguishing it from siblings like by_group. However, it is a fragment and could be more explicit about the action (e.g., 'Retrieve public uploads from a specific user').

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 usage guidelines are provided. The description does not mention when to use this tool over alternatives like by_group or compare_entities, nor does it give any 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?

Annotations indicate readOnly, openWorld, non-destructive. Description adds valuable behavioral context: replaces 8-15 sequential calls, returns paired data with citation URIs, and details data sources per type.

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

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

Three sentences, each earning its place: purpose, usage triggers, type-specific details with data sources. No redundancy, highly 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?

Despite no output schema, the description provides sufficient detail on what data is returned per entity type and that results include citation URIs. Covers all key aspects for an agent to decide and invoke.

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

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

Schema has 100% coverage. Description significantly enriches both parameters: for type, specifies the exact data pulled (revenue, income for company; adverse events, approvals for drug); for values, gives concrete examples (tickers vs drug names).

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

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

The description states a specific verb ('Compare') and resource ('2–5 companies or drugs'), clearly distinguishing it from sibling tools like entity_profile which cover single 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?

Provides explicit when-to-use triggers ('compare X and Y', 'X vs Y', 'how do X, Y, Z stack up') and separates company vs drug use cases. Lacks explicit when-not-to-use guidance.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds that it 'returns the top-N most relevant tools with names + descriptions,' which is useful context. No contradictions or hidden effects mentioned.

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

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

Description is front-loaded with the core purpose, then usage context, then concrete examples, and finally return details. Every sentence serves a purpose with no redundancy or filler.

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

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

For a simple discovery tool with no output schema, the description adequately explains the return value (names + descriptions). It covers the key aspects, though it could briefly mention how relevance ranking works.

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 both parameters. The description reinforces their meaning by mentioning 'top-N most relevant' for limit and provides natural language examples for query, adding value beyond the schema.

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

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

The description clearly states the tool's purpose: 'Find tools by describing the data or task.' It lists specific domains and distinguishes from sibling tools by being the only discovery/search tool, not performing a specific action like ask_pipeworx or 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?

Explicit guidance: 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' It also says when to use (browse, search, look up, discover) and gives concrete examples of tasks.

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 include readOnlyHint=true and openWorldHint=true. The description adds context beyond annotations: it returns pipeworx:// citation URIs, uses multiple data sources (SEC, USPTO, news, GLEIF), and specifies accepted input formats (ticker or CIK). 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 front-loaded with the core purpose, uses 3-4 sentences without redundancy. Every sentence adds value: usage triggers, return data, input format, and alternative tool for names.

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 comprehensively enumerates what is returned (SEC filings, revenue/net income/cash position, patents, news, LEI) and mentions citation URIs. For a multi-source aggregation tool, this is sufficiently complete.

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

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

Schema coverage is 100%. The description adds meaning: for 'type' it clarifies only 'company' supported (with upcoming options), and for 'value' it explains ticker or CIK, explicitly states names not supported, and directs to resolve_entity for names.

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

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

The description clearly states the tool's purpose: 'Get everything about a company in one call.' It lists specific return data (SEC filings, financials, patents, news, LEI) and distinguishes from sibling tools by noting it replaces calling 10+ pack 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 explicitly states when to use (e.g., user asks 'tell me about X', 'brief me on Tesla') and what not to use (if only a name, use resolve_entity first). It also explains the scope—aggregating multiple sources.

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 flag destructiveHint=true; description adds context about why deletion is appropriate (clearing sensitive data). No contradictions.

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

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

Two sentences; first states purpose, second gives usage guidance. No filler, front-loaded.

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

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

For a simple 1-parameter destructive tool with annotations, the description covers what, when, and why sufficiently.

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

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

Only one parameter (key) with 100% schema description coverage. Description does not add extra info beyond schema, so baseline score 3.

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

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

Description clearly states 'Delete a previously stored memory by key.' Verb and resource are specific. Distinguishes from siblings 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?

Provides explicit when-to-use scenarios: stale context, task done, clear sensitive data. Also mentions pairing with remember and recall. Lacks explicit when-not-to-use, but still strong.

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 details the process: fetches the page, extracts title/description/key links, and emits standard llms.txt markdown. This adds significant behavioral insight beyond annotations (readOnlyHint, idempotentHint, openWorldHint) 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 three sentences: first states purpose and benefit, second explains process, third lists use cases. No extra fluff, well-structured with front-loaded 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?

Given no output schema, the description explains the output format ('single text blob ready to drop at site-root/llms.txt'). It covers what, how, output, and use cases, making it 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% with parameter descriptions, so baseline is 3. The description adds context by explaining that the URL is the site to summarize and max_links controls link entries, enhancing meaning beyond the schema alone.

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

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

The description explicitly states the tool generates a production-ready llms.txt file for any URL, specifying the verb, resource, and outcome. It distinguishes from sibling tools like `ai_visibility_check` and `scan_competitor_ai_presence` by focusing on generating a specific file format for AI crawlers.

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 three specific use cases (client indexing, own project drafting, competitor auditing), providing clear context for when to use the tool. However, it does not explicitly exclude scenarios or mention alternative tools for comparison.

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 behavioral details beyond annotations: rate-limited to 5 per identifier per day, free, doesn't count against quota, and that the team reads digests daily. 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?

Concise and well-structured: front-loads purpose, then usage, then behavioral details. Every sentence is informative without redundancy.

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

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

Complete for a feedback tool with 3 parameters, one enum, and a nested object. Covers enum meanings, optional context, and message guidelines. No output schema needed.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining the enum values for 'type' and suggesting message length (1-2 sentences, 2000 chars max).

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: to provide feedback about bugs, missing features, data gaps, or praise. It distinguishes from sibling tools like ask_pipeworx and discover_tools by specifying exactly when to use it.

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

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

Provides explicit guidance on when to use (bug, feature, data_gap, praise) and what to avoid (don't paste end-user prompt). Also mentions rate limits and that it's free.

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

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

Annotations already indicate read-only, non-destructive, idempotent behavior. The description adds that it's derived from CF analytics-engine with no PII and is cached 5min-1h, providing valuable context beyond annotations.

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

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

Description is concise yet comprehensive: first sentence summarizes, then details parameter, use cases, technical notes. No extraneous content; 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 explains the output structure ('just (pack, tool, count)') and addresses caching, window behavior, and data provenance. Complete for agent use.

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

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

Schema covers the parameter fully with enum and description. The description adds rationale for window choices (hot right now vs steady-state) and notes default, providing additional semantic clarity.

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

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

The description clearly states the tool returns top tools, top packs, and total call volume over configurable windows, with specific use cases listed. This distinguishes it from sibling tools like pipeworx_feedback or discover_tools.

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

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

The description provides three explicit use cases and explains the window parameter trade-offs, but does not mention when to avoid using it or contrast with specific alternatives among siblings.

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

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

Annotations already indicate readOnlyHint=true and openWorldHint=true. The description adds valuable behavioral context beyond annotations: it walks child markets, extracts dates/thresholds, sorts them, and reports violations. 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 that efficiently packs purpose, condition, example, usage, and output structure. Every sentence earns its place, and the most critical info is front-loaded.

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

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

Given the simple input (one string parameter) and no output schema, the description fully explains what the tool does, how it works internally (walking markets, sorting, checking monotonicity), and what it returns. It is complete for the complexity level.

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 already describes the 'event' parameter as 'Polymarket event slug ... or full URL.' The tool description repeats this information without adding new meaning. Since schema coverage is 100%, baseline 3 applies.

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

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

The description clearly states the tool's purpose: 'Find arbitrage opportunities within a Polymarket event by checking for monotonicity violations.' It specifies the resource (Polymarket event) and action (find arbitrage), distinguishing it from sibling tools like 'polymarket_edges' or 'bet_research'.

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

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

The description gives explicit usage instructions: 'Pass a Polymarket event slug or URL.' It explains the condition for arbitrage (earlier market trading higher than later) and the output format. However, it does not explicitly state when not to use it or provide alternatives, but the context is clear.

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

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

Annotations (readOnlyHint: true, destructiveHint: false) indicate safe read-only behavior. The description adds significant behavioral context: explains the underlying model (lognormal from FRED + coinpaprika price), the process (scans, groups, fetches price history once, computes probability, ranks by |edge|), and the output (top N ranked by edge magnitude with suggested trade direction). 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 two sentences long with no wasted words. It front-loads the core purpose in the first sentence and provides necessary detail (model, process, output) efficiently. Every sentence adds value.

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

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

Given no output schema, the description explains the return value (ranked list with trade direction) and the scope (V1 covers crypto-price bets). It also provides context on the algorithm and limitations. This is sufficient for an AI agent to understand the tool's capabilities and decide to invoke it.

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

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

Input schema coverage is 100% — all three parameters (limit, window, min_edge_pp) have descriptions. The description reinforces their purpose (e.g., 'Top N edges' for limit, 'volume window' for window) but does not add new semantic meaning beyond the schema. With high coverage, the baseline of 3 is appropriate.

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

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

The description clearly states the tool's purpose: 'Scan the highest-volume Polymarket markets and return the ones where Pipeworx data disagrees most with the market price.' It identifies the resource (Polymarket markets), the action (scan and return disagreements), and distinguishes from sibling tools like 'by_group' or 'by_user' which serve different filtering needs. The mention of 'for the "what should I bet on today" question' further clarifies the specific use case.

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

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

The description implies when to use the tool: to discover betting opportunities without manual search. It mentions it is 'built for the "what should I bet on today" question' and that it 'discovers opportunities'. However, it lacks explicit guidance on when not to use it or alternatives (e.g., sibling polymarket_arbitrage might be for arbitrage) but the context is clear enough for an agent.

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

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

Beyond the readOnlyHint and idempotentHint annotations (which already signal safety), the description adds specific behavioral traits: the spread calculation (Kalshi minus Polymarket in percentage points), return of leg-by-leg prices, and the rationale for the spread (different participant pools). No contradictions with annotations.

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

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

The description is well-structured with two modes clearly separated and return values summarized. It is front-loaded with the core purpose. While slightly verbose, every major point is useful and earns its place.

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

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

Given no output schema, the description thoroughly explains return values (leg-by-leg prices and spread). It covers both usage modes, the rationale for the spread, and example parameter values, making it complete 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%, so baseline is 3. The description enhances this by explaining that 'topic' is a pre-mapped macro shortcut with examples, and that explicit parameters override topic mapping, adding context 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's purpose: computing cross-venue spreads between Kalshi and Polymarket. It specifies the verb 'spread' and the resources, distinguishes from sibling tools like polymarket_arbitrage by focusing on inter-venue comparison, and explains the two operational modes (topic and explicit) upfront.

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

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

The description provides clear context on when to use the tool (when venues price the same event differently) and explains the two modes with examples. However, it does not explicitly state when not to use it or mention alternative tools, though the unique purpose makes alternatives obvious.

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. Description adds value by explaining scoping to identifier and listing behavior when key is omitted, without contradicting annotations.

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

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

Three sentences, front-loaded with core functionality, no redundancy, every part contributes to understanding.

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

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

Covers purpose, parameter behavior, scoping, and pairing. Lacks explicit return format (e.g., string vs. array), but for a simple read tool with no output schema, it is mostly complete.

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

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

Schema coverage is 100%, so baseline is 3. Description adds meaning by explaining the effect of omitting the key (list all keys), which goes beyond the 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 explicitly states the tool retrieves a saved value or lists all keys, with clear verb-resource pairing. It distinguishes itself from siblings 'remember' and 'forget' by focusing on retrieval.

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

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

Provides concrete examples (target ticker, address, notes) and pairing guidance with 'remember' and 'forget'. Lacks explicit when-not-to-use, but context is sufficient for agent decision-making.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, making safety clear. The description adds that uploads are public and sorted by recency, but does not disclose additional traits like pagination or rate limits.

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

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

Single sentence that is front-loaded with the core purpose. No redundancy or filler.

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

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

With no output schema, the description should explain what fields are returned or any behavior like ordering/pagination. It lacks these details, making the tool's response shape unclear.

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

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

The input schema has 100% description coverage, so the schema already documents all parameters well. The description adds no extra detail beyond what is in the schema.

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

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

The description clearly states the tool returns the most recent public uploads with optional tag filtering. This is a specific verb-resource combination that distinguishes it from sibling tools like by_user or by_group.

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 by_user or recent_changes. No exclusions or context provided.

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

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

Beyond the readOnlyHint and destructiveHint annotations, the description reveals that it fans out to three external sources in parallel, explains the since parameter formats in detail, and specifies the return structure (changes, count, URIs). This is comprehensive 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, well-structured paragraph. It front-loads the purpose, then explains behavior, parameter details, and output. Every sentence earns its place with no unnecessary information.

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

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

Given the tool's moderate complexity, the combination of schema (100% coverage), annotations (readOnlyHint, openWorldHint, no destructive), and description fully covers purpose, parameters, behavior, and output. No gaps remain for an AI agent to interpret.

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

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

With 100% schema coverage, the baseline is 3. The description adds value by explaining the since parameter's flexible formats (ISO date and relative shorthand with examples) and clarifying that type is limited to 'company'.

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: 'What's new with a company in the last N days/months?' and provides specific example queries. It distinguishes itself from siblings like entity_profile and compare_entities by focusing on recent multi-source 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 explicitly says 'Use when a user asks...' and lists several natural language cues. It provides clear context for when to invoke this tool, though it does not explicitly discuss when not to use it or mention 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?

Describes scoping by identifier, persistence details (authenticated vs anonymous sessions, 24-hour retention), and implicitly reveals it is a write operation, consistent 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?

Three focused sentences front-loading purpose, then usage guidelines, then behavioral specifics; 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 two-parameter tool with no output schema, the description covers purpose, usage, and behavioral constraints completely.

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

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

Schema covers 100% of parameters with descriptions; the description adds value by explaining the key-value pair concept and providing naming conventions (e.g., 'subject_property').

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

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

The description clearly states the tool saves data for reuse, gives concrete examples (resolved ticker, address, preference), and distinguishes it from sibling tools (recall, 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 states when to use ('when you discover something worth carrying forward') and mentions associated tools (recall, forget) as 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 and destructiveHint; description adds return format (IDs plus pipeworx:// URIs) and example outputs, providing useful behavioral context beyond annotations.

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

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

Description is concise (5 sentences), front-loaded with purpose, includes examples, and every sentence adds value. No fluff.

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

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

For a 2-param tool with annotations, description covers purpose, input examples, output format, and usage guidance. Missing error handling or edge cases, but adequate for typical usage.

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

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

Schema coverage is 100% with descriptions; description enhances by giving practical input examples (e.g., 'Apple' → AAPL/CIK) and clarifying value formats for company and drug 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 clearly states the tool resolves entity names to canonical identifiers (CIK, ticker, RxCUI, LEI) for companies and drugs, with examples. It distinguishes itself from sibling tools as a prerequisite lookup.

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

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

Explicitly says 'Use this BEFORE calling other tools that need official identifiers.' Provides examples of when to use, but lacks explicit 'when not to use' or alternative tools.

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

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

Annotations already declare readOnly, openWorld, idempotent, non-destructive. Description adds that it internally calls ai_visibility_check and requires an API key for anthropic model. No contradictions; adds useful behavioral context beyond annotations.

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

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

Three sentences: main action, use case, return format. No extraneous words, front-loaded with the core purpose. Every sentence earns its place.

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

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

Covers input (entities, models, context, API key) and output (ranked list with score, confidence, signal density). Mentions subtool dependency. Complete for a tool with 4 parameters and no output schema.

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

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

Input schema has 100% description coverage. Description does not add detailed parameter semantics beyond summarizing that entities are compared and first is treated as subject. Baseline 3 is appropriate as schema already handles the heavy lifting.

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

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

Clearly states it compares AI visibility across multiple entities, probes with ai_visibility_check, ranks and surfaces most/least recognized. Verb 'compare' and resource 'AI visibility' are specific, and it distinguishes from the sibling ai_visibility_check which is for single 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?

Explicitly states use case: competitive AI-marketing audits. Provides a concrete example question. However, it does not explicitly say when not to use or mention alternatives like ai_visibility_check for single entities, though it's implied.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds valuable details about graceful partial failures and timing (5-30s first measurement), which is beyond annotations and clearly disclosed.

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

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

The description is front-loaded with purpose, but the second sentence is densely packed with return fields and alternative ecosystems, making it slightly verbose. Still, every sentence contributes 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 lists all returned fields (summary block, advisories, links, alternatives) and covers ecosystem limitations, partial failures, and timing, providing complete context for agent use.

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

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

With 100% schema coverage, the description still adds meaning by clarifying that scoped packages (e.g., '@types/node') are accepted and that version defaults to latest when omitted, enhancing 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 uses a specific verb ('composite check') and resource ('npm package'), and clearly distinguishes from sibling tools by focusing on npm ecosystem and combining deps.dev and bundlephobia data.

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

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

It explicitly states when to use (e.g., 'is X safe / popular / small') and what not to use (non-NPM ecosystems, pointing to deps.dev:version directly), leaving no ambiguity.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the tool is safe. The description adds detailed behavioral context: the return value includes a verdict, structured form, actual value with citation, and percent delta. It also explains that the tool replaces multiple calls, which is extra transparency 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 paragraph that front-loads the purpose, then gives usage context and output details. Every sentence contributes information, though some redundancy exists (e.g., 'confirm/refute' and 'check whether... is true'). Still, it is efficient and well-structured.

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

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

Given the tool's simplicity (one parameter, no output schema), the description is fairly complete. It explains scope, return format, and use case. It does not mention failure modes or prerequisites, but for a read-only, well-scoped tool the information is sufficient 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?

The input schema covers the single 'claim' parameter with 100% description coverage. The description adds value by specifying the supported claim type (company-financial) and example formats, which helps the agent construct valid inputs beyond the schema's basic type.

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

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

The description clearly specifies the tool's action (fact-check, verify, validate) and resource (natural-language factual claim). It differentiates by stating the supported domain (company-financial claims) and mentions it replaces multiple sequential calls, distinguishing it from siblings like ask_pipeworx or 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?

The description explicitly states when to use this tool: 'Use when an agent needs to check whether something a user said is true,' with example queries. It also notes the scope (v1 supports company-financial claims for US public companies) but does not explicitly name alternative tools for other claim types, missing a small opportunity for contrast.

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