Propublica Nonprofit

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 specifying the default free model, the need for a BYO key for Anthropic (cost implication), and the structure of the return value (per-model score, confidence, signals, raw_response, combined view). 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 approximately 70 words, with the main purpose stated first, followed by model details and use cases. No extraneous information. 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 adequately explains the return structure. It covers parameters, optionality, cost implications, and use cases. No missing critical information for an AI agent to decide on tool invocation.

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

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

Schema coverage is 100%, so the schema already documents parameters. The description enhances understanding by noting the default model ('Workers AI Llama-3.3-70b (free)'), the behavior of '_apiKey' ('passed straight through'), and the purpose of 'context' ('helps disambiguate common 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 probes LLMs for knowledge about an entity and returns a visibility score. It distinguishes itself from siblings like 'scan_competitor_ai_presence' by focusing on the probing and scoring aspect. The use of 'probe' is a specific verb and 'LLMs' is the resource.

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

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

The description explicitly lists use cases (AI-marketing audits, brand checks, competitive monitoring) and mentions default model and optional Anthropic key. It implies when to use but does not explicitly state when not to use or provide 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?

Even though annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, the description adds value by explaining the routing behavior, the large number of sources, the structured answer format with stable citation URIs, and that it works on every tier. No contradictions with annotations.

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

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

The description is about 150 words, every sentence adds value. It is front-loaded with the most important guidance (prefer over web search), followed by functionality, usage examples, and alternatives. Clear structure with no redundancy.

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

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

For a tool with no output schema, the description adequately explains that it returns structured answers with citation URIs. It covers input (question parameter), routing behavior, and integrates with the sibling ecosystem. Given the complexity of the tool, the description is comprehensive.

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

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

Schema description coverage is 100%, so the baseline is 3. The description provides examples of questions but does not add significant new meaning beyond what the schema already specifies. The alias descriptions are already comprehensive 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 routes questions to a large set of sources and returns structured answers with citations. It uses specific verbs like 'routes', 'fills arguments', and 'returns'. It distinguishes from siblings like ask_pipeworx_grounded and deep_research, making the purpose unambiguous.

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

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

The description explicitly advises to prefer this tool over web search and states it is the default entry point for most questions. It provides clear alternatives: use ask_pipeworx_grounded for hallucination-resistant answers, and deep_research for broad/multi-part questions. Examples of when to use are also given.

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

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

Discloses beta nature, candidate improvements, current inactive state, and that it falls back to nothing. Assures it is a full working router. Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint; description adds context about experimental edge and comparison process, enhancing 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?

Description is concise (4 sentences) and front-loaded with core purpose. Could be slightly more structured but is clear and informative. No wasted sentences.

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

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

Given the tool's complexity as a universal router, the description covers its beta nature, identity, and usage. No output schema exists, so description need not explain return values. Annotations provide safety profile. Missing examples or limitations, but sufficient for agent understanding.

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

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

Schema coverage is 100% with each parameter described as alias for 'question'. Tool description adds no additional parameter meaning beyond what schema provides. Baseline 3 applies because schema already documents parameters adequately.

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

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

Description explicitly states it is a beta version of ask_pipeworx, an identical universal router with candidate routing improvements. It clearly differentiates from sibling ask_pipeworx (stable) and describes its current state and behavior.

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 direct guidance: 'Use it exactly like ask_pipeworx when you want the newest routing.' Also clarifies current identity with stable router and that results are compared to decide merges. Contrasts with stable version without mentioning alternatives explicitly.

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

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

Discloses behavioral traits beyond annotations: details refusal reasons (4 types), structured output with evidence and confidence, cost of one extra LLM call. Annotations already indicate readOnly, openWorld, idempotent, non-destructive; description adds refusal behavior and output format without contradiction.

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

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

Description is four sentences with front-loaded purpose. All sentences add value: use case, process, output structure, cost tradeoff. Slightly lengthy but efficient given rich content.

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

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

Despite high complexity (large tool selection, many sources, no output schema), description fully covers purpose, usage, behavior, return structure including refusal reasons. Provides all necessary context for agent to 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% with aliases fully described. Description only restates that question accepts natural language; no additional semantic context beyond what the schema provides. Baseline score of 3 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?

Clearly states it is a hallucination-resistant answer mode for high-stakes reads. Describes the process: picks the right tool from 5,245 across 1369 sources, fetches data, and extracts answer using only the tool result. Distinguishes from sibling ask_pipeworx by noting extra cost and 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?

Explicitly advises when to use: 'whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts' with examples like financial verdicts, legal claims, medical lookups. Also tells to prefer ask_pipeworx for casual lookups, providing clear 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=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds extensive behavioral context: how the tool resolves markets, fans out to data sources, handles errors (low confidence, closed markets, wide spreads), and even cancellation rule risk. It explains blocking mechanisms and tradeability issues, going well beyond annotations.

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

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

The description is very long but well-structured with clear sections (RESPONSE SHAPES, RESOLVER CONTRACT, etc.) and front-loaded with the core action. Every sentence adds value, but the length could be slightly trimmed for efficiency. Still, it is organized and not rambling.

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 the tool (3 parameters, no output schema, numerous edge cases), the description is exceptionally complete. It covers resolver contract, parent event extraction, news fields with error handling, safety mechanisms, cancellation rules, and more. No meaningful gaps remain for an agent to be confused.

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

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

Schema coverage is 100%, with all three parameters described. The description adds substantial meaning beyond the schema: it explains the 'market' parameter accepts slug, URL, or question text; 'depth' enum is explained with defaults; 'include_raw' is explained with use cases. Examples are provided for market input. The description fully compensates for any schema brevity.

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 action (research), the resource (Polymarket bet), and the scope. It provides multiple input examples and classifiers, making the purpose very specific and distinguishable from sibling tools like 'polymarket_edges' or 'polymarket_arbitrage', even though not explicitly compared.

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 the tool: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It also provides extensive usage details, including classifiers, fan-out examples, and what to inspect (e.g., market_match_confidence). While it doesn't explicitly say when not to use it, the clarity of use cases is sufficient for an agent to decide.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds significant behavioral context: data sources (SEC EDGAR/XBRL for companies, FAERS/FDA for drugs), handling of off-calendar fiscal years, sorting by primary metric, and citation URIs. This goes well beyond what annotations provide.

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 compact yet comprehensive, front-loaded with user intent examples and core purpose. Every sentence adds non-redundant value: constraints, data specifics, ordering, and comparison to alternatives. No wasted words.

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

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

Given the tool's moderate complexity (two types, multi-entity comparison) and that annotations cover safety/idempotency, the description provides enough information for correct invocation. It explains return format (paired data + citation URIs) and covers key behavioral details. No major gaps identified.

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

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

Schema coverage is 100% with descriptions for both parameters. The description enriches by explaining what each enum value ('company', 'drug') pulls, and provides real-world examples for the 'values' parameter (tickers/CIKs for companies, drug names). It adds meaningful guidance for parameter selection.

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 comparisons of companies or drugs, with explicit intent examples ('compare X and Y', 'which is bigger'). It differentiates from sequential lookups and specifies the entity types, 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 explicitly says to ALWAYS PREFER this tool over sequential single-pack lookups when comparing entities, and provides context on when to use each entity type (company vs drug). It effectively guides the agent away from alternative approaches.

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

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

The description goes well beyond annotations by detailing the internal process: decomposition into facets, parallel routing to 5,245 tools, returning a findings packet with verbatim evidence, confidence, source, fetched_at, citation, gaps, and contradictions. It also explains response times (15-60s, thorough up to 90s), how large records are excerpted, and the behavior for different depths. This fully discloses non-obvious behaviors.

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

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

The description is long but every sentence adds value. It is front-loaded with the most critical information (account requirement, alternative tool). The structure uses clear sections and bullet points, making it scannable despite the length. No filler or redundant statements.

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 2 parameters, no output schema, and no nested objects, the description is remarkably complete. It covers input requirements, output structure, behavior for different depths, edge cases (e.g., large records excerpted), and limitations (gaps when topic not in catalog). The presence of detailed sibling context further supports 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?

Both parameters have 100% schema description coverage. The description adds significant meaning: for 'depth', it explains each enum value's effect (quick=3 facets, standard=5 with gap recovery, thorough=8 with iteration) and what to expect; for 'question', it clarifies that broad/multi-part questions are fine. This enriches the schema with practical context.

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

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

The description clearly states the tool performs 'Grounded multi-source research across Pipeworx's 1369 STRUCTURED data sources in ONE call'. It distinguishes from siblings by explicitly mentioning alternatives like ask_pipeworx for single lookups or current news, and emphasizes that this is not open-web search. The verb 'research' and the resource (structured data sources) are specific, making the purpose unambiguous.

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

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

The description provides explicit guidance on when to use this tool vs alternatives: 'For a single lookup use ask_pipeworx' and 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx'. It also states account requirements (free account needed, paid plan for thorough depth). This gives the agent clear decision criteria.

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

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

Annotations already indicate safe, idempotent, non-destructive. Description adds useful context about return format (full schemas with examples, ready to call). 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?

Front-loaded with purpose, every sentence adds value. Appropriate length for the tool's role.

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?

Explains output format (top-N tools with names, descriptions, schemas, examples) and when to use. No output schema needed given the description's clarity.

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

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

Schema coverage is 100%, so description adds little beyond restating aliases. 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?

Description states it finds tools by describing data or task, listing many domains. It clearly distinguishes itself from siblings like specific data 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 'Call this FIRST when you have many tools available' and describes when to browse, search, discover. Provides clear usage context.

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

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

Annotations already declare readOnly, openWorld, idempotent, non-destructive. Description adds context about fanning across multiple sources, patent sunset (soft-fail), and return format (URIs, sorted). No mention of rate limits or auth, but safety is covered by 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 comprehensive but front-loaded with examples and priority statement. Every sentence adds value, though slightly verbose. 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 2 parameters, 100% schema coverage, no output schema, and rich annotations, the description fully covers the tool's purpose, inputs, limitations, and outputs. 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% with descriptions. Description adds examples ('AAPL', '0000320193'), clarifies 'company' as only supported type, and specifies that names are not accepted. This goes beyond schema.

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

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

The description specifies 'full cross-source profile of a US public company in ONE parallel call' and lists exactly what it returns (CIK, filings, fundamentals, patents, news, LEI). It distinguishes from siblings by explicitly stating preference over chaining single-pack 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?

Describes when to use ('holistic view') and explicitly says 'ALWAYS PREFER over chaining single-pack...'. Also states when not to use: names not supported, and directs to resolve_entity. Clear alternatives provided.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true. The description adds context about why to delete (stale context, clear sensitive data) but does not elaborate on irreversibility or other behavioral details. It adds 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 concise—two sentences—with the action front-loaded. Every sentence contributes meaning 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?

For a simple tool with one parameter and no output schema, the description covers purpose, usage guidelines, and related tools. Annotations handle safety, so no gaps remain.

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

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

Schema coverage is 100% with a clear parameter description 'Memory key to delete'. The description does not add additional semantics for the parameter beyond what the schema provides. Baseline 3 is appropriate.

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

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

The description uses a specific verb 'Delete' and resource 'memory by key', clearly stating the action. It distinguishes from siblings by mentioning 'remember' and 'recall', which are related but serve different purposes.

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

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

The description provides explicit when-to-use scenarios: 'context is stale, the task is done, or you want to clear sensitive data'. It also suggests pairing with 'remember and recall', indicating 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, idempotentHint, and destructiveHint=false. The description adds behavioral details: it fetches the URL, extracts specific elements, and emits markdown. This adds value beyond annotations by explaining the operation flow and output format.

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 bulleted list of use cases. It is concise, front-loaded with the main action, and every sentence adds value. No unnecessary words or repetition.

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

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

Given the tool has 2 parameters, no output schema, and comprehensive annotations, the description fully explains what the tool does, how it works, and what the output is. No critical information is missing for an agent to correctly invoke and interpret the result.

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

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

Schema coverage is 100%, with descriptions for both parameters (url and max_links). The description does not add significant new information about parameters beyond what the schema provides; it mentions max_links default (25) and max (50) which are already in the schema. Baseline score of 3 is appropriate.

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

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

The description clearly states that the tool generates a production-ready llms.txt file for any URL, and explains the process (fetches page, extracts title/description/key links, emits markdown). It distinguishes itself from sibling tools by its specific purpose of creating llms.txt files for AI crawler indexing.

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

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

The description explicitly lists use cases: getting a client's site indexed, drafting llms.txt for your own project, or auditing a competitor. It does not provide explicit when-not-to-use or alternatives, but the listed use cases are clear and context-appropriate.

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 and behavior. The description adds value by listing return fields (revenue, expenses, assets, liabilities), enhancing 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 extremely concise—two sentences and an example—with no wasted words. It is front-loaded with the core purpose and includes a concrete example for 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?

For a simple tool with only 2 parameters, rich annotations, and an existing output schema, the description is fully adequate. It states the return content (financial data categories) without needing to duplicate schema details.

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 provides an example, but it does not add semantic meaning beyond what the schema's parameter descriptions already provide. The baseline score of 3 is appropriate.

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

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

The description clearly states the tool gets a specific IRS filing for a nonprofit, specifying the verb (get), resource (IRS filing), and scope (one tax period with financial data). The example further clarifies usage, distinguishing it from broader sibling tools like search_nonprofits or entity_profile.

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

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

The description implies usage for retrieving a single filing by EIN and tax period, but lacks explicit guidance on when not to use or alternatives. Given sibling tools like search_nonprofits and entity_profile, some implicit differentiation exists, but no direct exclusions are provided.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive. The description adds valuable context about return content (IRS filings with financial data), which goes beyond annotations and helps the agent understand the tool's output.

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

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

Two concise sentences: first defines purpose and key parameter, second adds what is returned with an example. 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?

Given the tool has one parameter, good schema coverage, and an output schema, the description fully covers the tool's purpose and what it returns. No missing information.

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

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

Schema coverage is 100% with a good description for 'ein'. The description adds an example and a real-world reference (American Red Cross), enhancing the schema's meaning.

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

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

Clearly states it retrieves full nonprofit details by EIN, specifying the resource and parameter. Distinguishes from siblings like entity_profile or get_filing by focusing on organization details plus IRS filings.

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 an example but no explicit guidance on when to use this tool versus other tools like search_nonprofits or entity_profile. Does not mention when not to use it or 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, destructiveHint. Description adds context about default filtering (active subscriptions) and the optional include_inactive parameter, 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?

Two sentences, front-loaded with core purpose and returned fields. No wasted words.

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

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

For a simple list tool with no output schema, the description includes all returned fields, explains the optional parameter, and gives use-case guidance. Complete for agent invocation.

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

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

Schema has 100% coverage for the single parameter, describing it fully. Description does not add new parameter details beyond reinforcing the default active filter, so score is baseline 3.

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

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

The description clearly states 'List the caller's active subscriptions' and lists the returned fields (id, type, params, etc.), distinguishing it from siblings like subscribe and unsubscribe by stating its use to review monitoring and find ids to cancel.

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: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' Implies when to use, though does not explicitly state when not to use.

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

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

Discloses rate limit (5 per identifier per day), free usage, no quota impact, and that team reads daily. Annotations are all false, and description adds meaningful behavioral context without contradiction.

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

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

Four sentences with clear front-loaded purpose. Every sentence adds value (usage, behavior, restrictions) with no redundancy.

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

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

For a simple feedback tool with 3 parameters and no output schema, the description covers usage, limitations, and behavioral expectations thoroughly. No gaps remain.

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

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

Schema already describes all parameters with 100% coverage. The description adds value by explaining type enum usage, context object optionality, message character limit, and provides usage guidance per 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 states the tool sends feedback (bug, feature, data_gap, praise) to the Pipeworx team, using specific verbs and resource. It clearly distinguishes from sibling tools, which are all query/analysis tools, making this the only feedback tool.

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

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

Explicitly lists when to use (bug, feature, data_gap, praise) with examples, and what not to do (don't paste end-user prompt). Mentions rate limits and quota, providing clear context for selection vs alternatives.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds valuable behavioral context: no PII, derived from CF analytics-engine, and caching delays (5min-1h). 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 moderately long but well-structured, starting with the core purpose, followed by use cases, then technical details. Every sentence adds value, with no redundancy.

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

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

Despite no output schema, the description sufficiently hints at the return format ('top tools, top packs, and total call volume'). The caching details and data source explanation provide adequate context for a simple trending 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 'window'. The description adds meaning beyond the schema by explaining the effect of shorter vs. longer windows ('surfaces what's hot right now' vs. 'steady-state demand'), which helps parameter selection.

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

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

The description clearly states the tool returns 'top tools, top packs, and total call volume' over a recent window, with a specific verb ('returns') and resource. It effectively differentiates from siblings like 'discover_tools' by focusing on trending usage derived from other AI agents.

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

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

Three explicit use cases are provided (discovering hot data sources, confirming canonical choice, aligning use case). While it doesn't explicitly state when not to use the tool, the context is clear and helpful for 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 indicate read-only, open world, idempotent, non-destructive. Description adds detailed behavioral context: fill check against live book, semantic anchor for cross-event pairs, partition filter for placeholders, and response structure. 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 comprehensive but somewhat verbose, with detailed explanations of internal logic (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK). It is well-organized with clear sections, but could be slightly more concise while retaining essential 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 no output schema, the description thoroughly explains the response structure (opportunities array with fields, partition check object). It covers all major aspects: modes, filters, edge cases (realizable edge <= 0), and references sibling tool for custom sizing. Comprehensive 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, but the tool description adds significant context: explains each mode's purpose, provides examples of valid inputs (event slugs, topic questions), and clarifies the output behavior for each parameter.

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 using monotonicity violations and partition-sum checks. It distinguishes itself from sibling tools like polymarket_edges and polymarket_fill_risk by focusing specifically on arbitrage.

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 on when to use each mode: no args for trending scan, event for specific market, topic for cross-event scanning. Recommends event mode for known events and warns when not to trade (realizable_edge_pp <= 0). References sibling tool for custom sizing.

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

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

Provides extensive behavioral details beyond annotations: caching strategy, response structure with by_segment and _diagnostics, model family specifics, edge calculation, and warning about market moves. No contradiction with annotations, which indicate read-only and idempotent behavior.

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 verbose but well-structured: starts with purpose, then breaks down model families, response fields, knobs, and diagnostics. Each sentence adds value given the tool's complexity, though could be slightly more concise.

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

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

Given 9 parameters with full schema coverage, no output schema, and a complex response, the description thoroughly covers expected output, caching, filtering knobs, and diagnostics, leaving little ambiguity for the agent.

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

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

Schema coverage is 100% with detailed descriptions for each parameter. The description does not add significant new meaning beyond what the schema already provides for parameters, meeting baseline but not exceeding it.

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

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

Clearly states it scans Polymarket markets and returns opportunities where Pipeworx data disagrees with market price. The 'what should I bet on today' use case and mention of avoiding paging through hundreds of markets distinguishes it from sibling tools like polymarket_arbitrage or polymarket_edge_tracker.

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 frames the tool for daily opportunity discovery and mentions tradeable-edge knobs as filters. However, no explicit when-not-to-use or alternatives are stated, though the context of siblings implies 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 declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds significant behavioral context: daily snapshots, 60-day TTL, decay computed from daily closes, not intraday, and detailed response structure with interpretation of fields like trend and decay_pp_per_day.

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, front-loading the purpose, then describing response fields, and ending with limitations. It is somewhat verbose but each sentence adds value given the complexity of the data.

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

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

Despite no output schema, the description thoroughly covers all response fields (tracked, expired, snapshot_dates), their substructures, and interpretation guidance. It also explains limitations and edge cases (e.g., gaps in snapshots). This is complete for a data retrieval tool.

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

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

Schema coverage is 100%, and the description adds context beyond the schema: explains 'snapshot family', default and clamp ranges, and that snapshots are written on cache-miss. This helps the agent understand parameter semantics beyond basic type and default.

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

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

The description clearly states the tool provides 'edge persistence and decay telemetry' from snapshots, answering the specific question of how long an edge has existed and if it's shrinking. It distinguishes itself from siblings like polymarket_edges by focusing on telemetry over time.

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

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

The description explains when to use this tool (to understand edge persistence vs. current edges) and provides context with the example of a fresh vs. old wide edge. It does not explicitly state when not to use it, but implies it when needing current edges, polymarket_edges is better.

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

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

Annotations already indicate readOnlyHint: true and idempotentHint: true. The description adds critical behavioral context: walks order book ladder, returns specific fields (top_of_book, vwap_fill_price, slippage, etc.), and warns about forced_directional_risk and thin legs. 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 capitalized mode headers and bullet-like details, but it is lengthy. Every sentence adds value, so it earns its place, though a slightly more concise phrasing 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 the tool's complexity (two modes, financial risk) and no output schema, the description is remarkably complete. It covers all input parameters, details return fields for both modes, and provides behavioral warnings. It fully compensates for the lack of output schema.

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

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

Schema coverage is 100%, but the description adds substantial meaning: explains default side behavior ('auto from partition sum'), interpretation of size_usd for buys vs sells and basket (settlement notional), and default values. The description of side parameter clarifies two different modes of operation.

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

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

The description clearly states it performs a 'realizable-vs-theoretical edge check against live CLOB order-book depth' and distinguishes two modes (single-market and basket), with specific verb+resource. It differentiates from sibling tools like polymarket_arbitrage and polymarket_edges by focusing on fill risk assessment.

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

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

Explicitly states when to use: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. Also explains risks of not using it (partial basket fills convert arb into unhedged directional position) and when theoretical edge is not capturable.

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 safe read-only, idempotent behavior. The description adds extensive behavioral context: compatibility warnings, temporal alignment checks, skipped cross types, and when spreads are meaningless. 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 verbose but well-structured with bold headings and paragraph breaks. Front-loaded with purpose, then details. Every sentence adds value, but could be more concise.

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

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

Given no output schema, the description fully explains the response structure (leg-by-leg prices, spreads, safety fields, temporal alignment). Covers potential warnings and edge cases comprehensively for a moderately complex tool.

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

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

Schema coverage is 100%, so baseline is 3. The description adds significant extra meaning: explains the two modes, provides examples, and clarifies when to use topic vs explicit tickers, which goes beyond parameter descriptions.

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

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

The description clearly states it is a 'Cross-venue spread between Kalshi and Polymarket for the same resolving question,' with specific verb and resource. It distinguishes itself from sibling tools like polymarket_arbitrage by focusing on cross-venue comparison and detailing two modes of use.

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 for when to use the tool, including warnings about real spreads being rarer and compatibility warnings. However, it does not explicitly mention alternative tools or when not to use it in favor of another.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint as true, true, and false respectively. The description adds value by explaining scoping (anonymous IP, BYO key hash, account ID) and the behavior when key is omitted (list all keys), but does not contradict annotations.

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

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

The description is concise (three sentences) and front-loaded with the core purpose. Every sentence adds value: purpose, usage context, scoping, and pairing with siblings. No wasted words.

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

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

Given one optional parameter, complete schema coverage, and annotations covering read-only/idempotent behavior, the description fully addresses the tool's complexity. It covers purpose, usage, scope, and relations to siblings. The absence of an output schema is acceptable for a simple 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% (single optional 'key' parameter). The description adds meaning beyond the schema by explaining the effect of omitting the key (list all keys) and the scoping behavior. It effectively tells the agent how to use the parameter.

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

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

The description clearly states the tool retrieves a value saved via 'remember' or lists all keys if the key argument is omitted. It distinguishes itself from siblings by naming 'remember' and 'forget' explicitly, providing clear 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?

Includes explicit guidance on when to use ('look up context the agent stored earlier') and how to use it effectively ('avoid re-deriving'). It also names sibling tools for complementary actions, providing a complete usage narrative.

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

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

Annotations already indicate read-only and idempotent behavior. The description adds valuable behavioral context: the mark_read side effect, polling compatibility, and the structure of returned data (source, citation_uri). 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, well-organized paragraph that front-loads the core purpose, then efficiently lists features and usage notes. Every sentence earns its place; 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?

Despite lacking an output schema, the description covers the return structure (source, citation_uri, raw payload), parameter behaviors, usage scenarios (polling, scripting), and an alternative access method. This is sufficient for an agent to use the tool correctly.

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

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

Schema coverage is 100% with descriptions, but the description further enriches parameter meaning with a concrete example for type ('sec_8k'), format requirement for since (ISO timestamp), and behavioral explanation for mark_read. This adds significant value beyond the schema.

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

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

The description opens with a specific verb-resource pair ('Pull fired events from your subscription feed') and clearly defines what the tool returns (source, citation_uri, raw event payload). It distinguishes itself from siblings like subscribe and list_subscriptions by focusing on reading persisted alerts.

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 filtering options (type and since), explains the mark_read behavior for call sequencing, and mentions an alternative endpoint for scripts/dashboards. However, it does not explicitly contrast with other read tools like recall or discover_tools, leaving some 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?

Adds rich context beyond annotations: details multiple data sources with fallback behavior (GDELT→GNews on rate limit/5xx), USPTO soft-fail, parallel execution, and output structure. Annotations already declare safe, idempotent, read-only behavior, and description aligns.

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

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

Front-loaded with purpose and examples, structured clearly with sources, parameters, output, and usage distinction. Slightly long but every sentence adds value.

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

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

No output schema, but description explains return format (changes[] grouped by source, total_changes, citation URIs). Covers all key aspects: multiple sources, failures, parameter usage, and alternative tool. Complete for 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?

Schema coverage is 100%, so baseline is 3. Description adds format details for `since` (ISO or relative), example values for typical use, and clarifies that `value` can be ticker or CIK. Adds meaningful context.

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

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

The description clearly states the tool provides a change feed for a company in a specified time window, using examples like 'what's new with X' and distinguishes from sibling `entity_profile` for static profiles.

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

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

Explicitly says when to use this tool vs `entity_profile`, and recommends '30d' or '1m' for typical monitoring. Also implies use for temporal updates.

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

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

Beyond annotations (readOnlyHint=false, idempotentHint=true, destructiveHint=false), the description adds critical context: scoping by identifier, persistence difference between authenticated (permanent) and anonymous (24 hours), and pairing with recall/forget.

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, front-loaded with purpose, and each of the four sentences serves a distinct function: purpose, usage scenario, storage details, and pairing advice. No wasted words.

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

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

Given the tool's simplicity (2 required params, no output schema), the description fully covers purpose, usage, behavior, and related tools. No gaps remain for an agent to wonder about.

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?

While schema coverage is 100%, the description adds value by providing example key patterns and stating that values can be any text like findings, addresses, etc., which aids correct parameter usage.

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

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

The description clearly states 'Save data the agent will need to reuse later' with a specific verb and resource. It distinguishes itself from siblings by mentioning recall and forget explicitly, and notes scope and persistence.

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

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

Explicitly says 'Use when you discover something worth carrying forward' and provides clear pairings with recall (retrieve) and forget (delete). This guides the agent on when and how to use the tool.

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

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

Annotations already indicate read-only, idempotent, non-destructive. Description adds that calls cascade internally through multiple lookups, replacing 2-3 manual steps. 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 natural language examples. Uses bullet-style formatting for supported types. Each sentence serves a purpose. Slightly verbose but efficient overall.

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

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

Given the complexity of two entity types with internal cascading lookups and no output schema, the description fully explains expected return values (ticker, CIK, RxCUI, citations). Provides a complete picture for agent 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 100%. Description enriches by providing concrete input examples (e.g., 'AAPL', '0000320193', 'ozempic') and notes auto-disambiguation for company. Adds practical guidance beyond 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?

Description clearly states the tool resolves names to canonical IDs (ticker, CIK, RxCUI) for company and drug entities. Uses specific verbs and resources, distinguishes from siblings by specifying it's the first tool to use when needing an ID from a name.

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 to use this tool 'FIRST whenever you have a name but need an ID'. Lists supported types with examples. Lacks explicit when-not-to-use or alternative tools, but context from sibling names helps differentiate.

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 non-destructive. The description adds significant behavioral detail: it probes each entity with ai_visibility_check, ranks by score, surfaces most/least recognized, and returns score, confidence, and signal density per entity. No contradictions.

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

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

Three sentences, each adding value: purpose, how it works, and an example use case. No redundant information; well-structured and front-loaded.

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

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

Given no output schema, the description adequately describes return fields (score, confidence, signal density) and indicates a ranked list. It covers the workflow and primary behavior, though it could briefly mention response format (e.g., JSON array). Still sufficient for agent invocation.

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

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

Schema coverage is 100% with descriptions for all 4 parameters. The description adds extra semantics: first entity treated as 'subject' for narrative, rest as competitors. This goes beyond what schema provides, justifying a score above 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 compares AI visibility across multiple entities side-by-side, ranks them by score, and identifies most/least recognized. It distinguishes from sibling tool ai_visibility_check (single entity) and compare_entities (generic comparison) by specifying the AI visibility focus.

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

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

The description provides explicit usage context: 'Useful for competitive AI-marketing audits' and includes an example question. While it doesn't explicitly state when not to use, the context is clear enough to guide selection 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 declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false. The description adds substantial context: composite nature, fans out to deps.dev and bundlephobia, returns summary block and per-advisory detail, partial failure degradation, and bundlephobia's first measurement delay. 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 long but efficiently packs critical information. It is front-loaded with the core purpose and follows with key details. Minor opportunity to tighten the sentence about other ecosystems, but overall clear and 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?

With only 2 parameters, 100% schema coverage, and no output schema, the description fully explains the return structure (summary block, advisories, links, alternative versions) and partial failure behavior. It is complete for this tool's complexity and 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%, but description adds useful semantics: scoped packages accepted for 'package', defaults to latest version when 'version' omitted. This clarifies expected usage 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 clearly states it is a composite check for npm packages covering license, advisories, version history, and bundle size. It uses the specific verb 'scan' and resource 'dependency', and distinguishes from siblings by noting it is NPM-only and mentions alternatives for other ecosystems.

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

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

Explicit usage guidance: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me". It also notes limitations (NPM only in v1) and handles partial failures gracefully, providing clear when-to-use and when-not-to-use 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, openWorldHint, idempotentHint, and destructiveHint. Description adds the specific return fields and an example, which is helpful but does not significantly add behavioral context beyond what annotations provide.

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, zero waste. Purpose is front-loaded. Every sentence serves a purpose: purpose, return fields, example, pointer to sibling.

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 output schema exists, description does not need to explain return values. It mentions key fields, gives an example, and references the sibling tool get_organization. No gaps for a straightforward search tool.

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

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

Schema description coverage is 100%, so baseline is 3. Description adds value with an example and clarifies that state is a two-letter code for filtering, providing extra context beyond the schema's descriptions.

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

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

Description clearly states 'Search US nonprofits by name' and lists returned fields (EIN, name, city, state, revenue, assets, NTEE code). Distinguishes from sibling get_organization by specifying it uses EIN for full details.

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 an explicit example and directs users to use get_organization for full details, giving clear guidance on when to switch to a sibling tool. No mention of when not to use this tool or other alternatives, but the explicit pointer is 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?

Annotations already indicate safe, idempotent, open-world behavior. Description adds beyond: truncation cap (200K chars), embedding model (BGE-base-en), window size (500-char overlapping), and that offsets enable verification. No contradictions.

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

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

Well-structured with key info front-loaded. Slightly dense but every sentence adds value. Could be trimmed slightly but remains efficient.

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

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

Given no output schema, description explains return format (passages with offsets and scores). Covers usage, constraints, and peer tool reference. Complete for a 3-param tool.

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

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

Schema coverage is 100%, baseline 3. Description adds examples for query parameter and default/range for limit, slightly improving understanding beyond schema.

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

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

Description clearly states it performs semantic search inside a fetched record, with specific verb 'semantic search' and resource 'record'. It distinguishes from siblings by mentioning pairing with ask_pipeworx_grounded.

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

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

Explicitly states when to use (record too big for prompt), what it saves (context), and pairs with ask_pipeworx_grounded for grounding over passages. Provides clear context for use vs alternatives.

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

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

Discloses behavioral details beyond annotations: returns new subscription ID, always-on feed plus optional channels, SMS limits (10/day), webhook signing and auto-disable after 10 failures. Annotations indicate idempotentHint=true, but description doesn't address idempotency; however 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?

Packed with essential information in a structured format, using bullet-like examples. Slightly long due to thoroughness, 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?

Covers all aspects: prerequisites, types, params, delivery, limits, and return value. No output schema, but description states it returns subscription ID. Adequate for a complex tool with 3 params and nested objects.

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 adds substantial meaning for each parameter, including type-specific params with examples and delivery channel requirements (e.g., E.164 format, verified phone).

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

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

Description clearly states the tool creates a proactive monitoring subscription to a live-data event stream. It distinguishes from sibling tools like list_subscriptions, unsubscribe, and recent_alerts by focusing on creation, subscription types, and delivery channels.

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 context for use: setting up proactive monitoring, requiring a Pipeworx OAuth account, and listing supported types with examples. Does not explicitly state when not to use, but preconditions and alternatives are implied through sibling tool names.

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

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

Annotations already declare the tool safe, read-only, and idempotent. The description adds valuable context: it returns live example questions with exact tool/argument shapes, and explains the no-argument vs topic-filtered behavior. No contradictions found.

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 natural language questions and a clear purpose statement. While it is somewhat verbose, every sentence contributes useful information (purpose, examples, usage, parameter details). Could be slightly more concise but structure is 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?

For a simple tool with one optional parameter and no output schema, the description provides complete context: what it returns, when to use it, how to call it with/without arguments, and even lists sibling meta-tools to learn about. 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% with a single optional parameter. The description enriches it by listing all possible topic values explicitly (finance, pharma, economics, etc.) and clarifying what happens when omitted ('cross-category spread'), going beyond the schema's brief 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 uses specific verbs ('returns category-bucketed example questions') and clearly identifies the tool as an onboarding entry point. It distinguishes from siblings by positioning it as the first tool to call when the agent doesn't know Pipeworx's capabilities.

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

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

Explicitly states 'Use this FIRST when you do not yet know what Pipeworx can do for you' and explains its role in learning about meta-tools. It does not provide explicit when-not-to-use scenarios, 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?

Annotations indicate idempotent and non-destructive. Description adds that ownership is enforced and the row is deactivated (not deleted), which provides useful behavioral context beyond annotations. Could be more explicit about exactly-once semantics.

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

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

Two sentences, front-loaded with the primary action, followed by key behavioral notes. 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 mutation with one parameter and no output schema, the description covers side effects, ownership, and relation to existing tools, making it complete.

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

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

Schema has 100% coverage with a clear description of the 'id' parameter. Description mentions 'by id' but adds no new information beyond the schema, so baseline score of 3 is appropriate.

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

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

Description uses specific verb 'Cancel' and resource 'subscription by id'. It also distinguishes from subscribe (which creates) and mentions ownership enforcement, making the purpose unambiguous.

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

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

Description states ownership enforcement and explains that the row is deactivated not deleted, with historical events still accessible via recent_alerts. It implicitly guides when to use but does not explicitly mention alternatives or 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 (readOnlyHint, openWorldHint, idempotentHint, destructiveHint false) are already present, but the description adds rich behavioral context: it details the two distinct processing pipelines (financial vs. other), the exact verdict set (5 values), the use of pipeworx:// citations, and the purpose of tolerance_pct. No contradictions with annotations.

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

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

The description is a single dense paragraph that front-loads the purpose with clear examples. Every sentence adds value: list of trigger phrases, use case, two processing paths, verdict types, and efficiency claim. 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?

Despite no output schema, the description explicitly lists the return components (verdict, actual value with citation, reasoning). It covers all important aspects: input requirements, processing logic, and output shape. For a tool with two complex processing paths, this is fully complete.

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

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

Schema coverage is 100%, but the description adds critical context: it explains the claim field with natural-language examples, describes tolerance_pct's role as an override with suggested values (1-2 for hallucination detection) and the default behavior. This goes significantly 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 opens with natural-language examples of the tool's trigger phrases ('Is it true that…', 'fact check', etc.), then clearly states it verifies claims against authoritative sources. It distinguishes two distinct processing paths (structured SEC EDGAR+XBRL for company-financial claims vs. grounded pipeline for any other factual claim) and explains the verdict types returned. This is a specific, resourceful verb with clear scope, differentiating it from sibling 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 'Use whenever the agent needs to check whether something a user said is factually correct' and lists example query types. It does not provide a when-not-to-use or explicit alternative sibling names, but the detailed explanation of what the tool covers and its efficiency (replaces 4-6 sequential calls) implicitly guides appropriate usage.

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