Notion_connect

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

The description explains that the tool picks the best data source, fills arguments, and returns results. This clarifies its internal behavior. However, it doesn't disclose potential limitations like latency, cost implications, or data freshness. No annotations are provided, so the description carries full burden; it does well but could be more transparent about edge cases.

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

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

The description is concise with three sentences, each adding value. It front-loads the core action and provides examples. Could be slightly tighter by removing the last sentence examples if redundant, but overall 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 the simple schema (1 param, no output schema), the description is nearly complete. It explains the tool's function, usage pattern, and gives examples. It doesn't mention return format, error handling, or scope limitations, but these are less critical for a natural language interface tool.

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

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

The description adds meaning beyond the input schema by explaining that the single parameter 'question' should be a natural language request, and provides examples. Schema coverage is 100%, so baseline is 3. The description adds context about how the question is processed (tool selection, argument filling), justifying a higher score.

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

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

The description clearly states the tool's purpose: to answer plain English questions using the best available data source. It distinguishes itself from siblings by emphasizing that it selects the right tool and fills arguments automatically, which is unique among the listed 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 tells when to use this tool: when you want to ask a question in plain English without browsing tools or learning schemas. It provides examples that clarify the range of queries, and implicitly advises against using sibling tools directly when this agent can handle routing.

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

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

Annotations provide readOnlyHint=true, openWorldHint=true, destructiveHint=false. The description adds significant behavioral details: it resolves the market, classifies the bet type, fans out to relevant packs, and returns an evidence packet plus comparison. It also notes this is the core demo product, adding insight into agent performance. No contradiction with annotations.

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

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

The description is a single paragraph that is front-loaded with the core purpose. It contains no wasted sentences, but is somewhat dense. It could be structured more clearly (e.g., separate input, process, output). Still, every sentence adds value.

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

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

Given no output schema, the description explains the return format (evidence packet + comparison). It covers input options, classification, and fan-out. Missing are error handling or limitations, but overall complete for a complex tool.

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

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

Input schema covers both parameters with descriptions (market: slug/URL/question text; depth: quick/thorough with default). Schema description coverage is 100%, so baseline is 3. The description adds minimal extra meaning (e.g., fan-out logic for depth) but not enough to raise the score.

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

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

The description clearly states the tool's purpose: research a Polymarket bet by pulling Pipeworx data. It specifies the inputs (slug, URL, question text) and outputs (evidence packet, market-vs-model comparison). The verb 'Research' and resource 'Polymarket bet via Pipeworx' are specific, and it distinguishes from sibling tools like ask_pipeworx or entity_profile by focusing on bets.

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 use cases: 'should I bet on X?', 'what does the data say about this Polymarket market?', or 'is there edge in this bet?'. It does not explicitly mention when not to use or alternatives, but given its unique purpose for bets, usage context is clear. A score of 4 reflects clear context without exclusions.

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

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

No annotations provided, so description carries full burden. It describes the data source (SEC EDGAR, FDA), return format (paired data + URIs), and efficiency gains. It doesn't mention read-only status or error handling, but the behavior is adequately clear for an agent.

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 extremely concise: four short sentences covering purpose, type-specific details, return format, and efficiency. 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?

Given only two parameters and no output schema, the description sufficiently explains the tool's inputs and outputs. It covers the types of entities, data returned, and the benefit of replacing multiple calls. Lacks detail on error handling or edge cases, but adequate for typical use.

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

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

Schema coverage is 100% with descriptions for both parameters. The description adds value by explaining how each type maps to specific data outputs, helping an agent understand the parameters' purpose and usage examples beyond the schema.

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

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

Description clearly states it compares 2-5 entities side by side, specifying two distinct types (company and drug) with concrete data points from SEC EDGAR and FDA, and mentions it replaces multiple sequential calls. This distinguishes it from sibling tools like resolve_entity or notion_*.

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

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

Description provides clear context: when to compare multiple entities efficiently in one call. It explains what data is returned for each type, implying when it's appropriate. However, it does not explicitly state when not to use it or suggest alternative tools for single-entity queries.

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

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

Without annotations, the description carries the full burden. It discloses that the tool returns the most relevant tools with names and descriptions, and that it uses natural language queries. However, it does not specify whether the search is case-sensitive or if there are any performance implications, but the behavioral description is sufficient for a search tool.

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

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

The description is two sentences with clear front-loading: the first sentence states the core purpose, and the second provides usage guidance. Every word is meaningful, 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?

Given that there is no output schema, the description does not explain the return format beyond 'names and descriptions', which is adequate for a search tool. It also provides important context about when to use it (500+ tools). It could be slightly improved by mentioning pagination or sorting, but overall it is sufficient.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds context by explaining that the query is a 'Natural language description', but does not elaborate on the limit parameter beyond what the schema already provides. Thus, it meets the baseline without adding significant extra value.

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

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

The description uses specific verbs ('Search', 'Returns') and a clear resource ('Pipeworx tool catalog'). It distinguishes itself by instructing to call this tool first when many tools are available, setting it apart from other tools that perform different tasks.

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

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

The description explicitly states when to use this tool ('Call this FIRST when you have 500+ tools available and need to find the right ones'), which provides clear guidance. It implies the tool is for discovery rather than direct action, effectively guiding the 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?

No annotations provided, but the description details the data sources and that it returns citation URIs. It does not explicitly state it is read-only or idempotent, but given it's a profile lookup, this is a minor omission. It adds behavioral context about bundling multiple calls.

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

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

The description is concise with five sentences that front-load the main purpose. Every sentence adds value, with no redundancy. It is well-structured for quick comprehension.

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

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

The description covers usage scenarios and data sources adequately, but lacks details on the output format or structure. With no output schema, the agent may not know how to parse the result. Error handling or missing entity cases are not mentioned.

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

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

Schema coverage is 100% with clear descriptions for both parameters. The tool description adds context about input formats (ticker or CIK) and the scope of data retrieved, enriching the parameter understanding beyond the schema.

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

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

The description clearly states it retrieves a full entity profile across multiple data sources, using a specific verb and resource. It effectively distinguishes from sibling tools like resolve_entity and mentions an alternative tool (usa_recipient_profile) for federal contracts.

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 explains when to use this tool (to get comprehensive profile in one call) and when not (for federal contracts, use usa_recipient_profile). It also advises using resolve_entity first if only a name is available.

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?

No annotations are provided, so the description carries the full burden. It states the action is 'delete,' implying it is destructive, but does not mention irreversibility, permissions needed, or what happens if the key does not exist.

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 sentence with no wasted words, perfectly concise for a simple tool.

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

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

Given the tool's simplicity (1 required parameter, no output schema), the description is adequate but could mention return behavior (e.g., success confirmation) or error conditions.

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 no extra meaning beyond the schema. The parameter 'key' is described similarly in both, so the description provides no additional semantics.

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

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

The description clearly states the action (delete) and the resource (stored memory by key), distinguishing it from sibling tools like recall and remember which are for reading or storing memories.

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

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

No guidance is provided on when to use this tool versus alternatives like recall or remember. The description does not mention prerequisites or when deletion is 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?

No annotations provided. Description states it returns schema, properties, and metadata but does not disclose behavioral traits like read-only nature, rate limits, or what happens if database not 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?

Single sentence that is clear and front-loaded with action and object. 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?

With only one parameter and no output schema, the description adequately explains input and output, but lacks details on error handling or additional constraints.

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 database_id. The description adds context that the ID is UUID format and flexible with dashes, which is helpful 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 clearly states it gets a Notion database by ID and returns schema, properties, and metadata. It distinguishes from sibling tools like notion_get_page (gets a page) and notion_query_database (queries a database) but doesn't explicitly differentiate.

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

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

No explicit when to use vs alternatives, but the purpose is clear: retrieving database metadata. Sibling names suggest other tools for pages or queries, implying this is for the database object itself.

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 are empty, so description carries full burden. It states the tool retrieves a page and returns properties/metadata, but does not disclose any behavioral traits such as rate limits, required permissions, or whether it supports archived pages. Adequate but lacks depth.

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 two sentences, concise and front-loaded with the core action. No extraneous information, but could be more structured.

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

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

Given the tool's simplicity (one parameter, no output schema), the description is adequate. However, it does not specify the return format or potential errors, which could be useful for an agent. Without annotations, slightly more detail would improve completeness.

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

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

Schema coverage is 100% for the single parameter 'page_id', which has a description. The tool description adds no additional meaning 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?

Description clearly states it gets a Notion page by ID, returning properties and metadata. The verb 'Get' and resource 'page' are specific, distinguishing it from siblings like notion_get_database and notion_query_database.

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 does not explicitly state when to use this tool vs alternatives like notion_search or notion_list_pages. It implies usage for retrieving a single page by ID, but lacks guidance on when not to use it.

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

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

Annotations are empty, so the description carries full burden. It states it uses search with a page filter, which hints at behavior, but does not disclose limitations like potential missing pages due to integration access or search indexing.

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, clear and to the point. Could be slightly more concise by removing 'Uses search with page filter' if that is already implied by the tool name, but it is still 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?

For a simple list tool with 2 parameters and no output schema, the description is reasonably complete. It explains the scope (accessible pages) and method (search with page filter). No further details are needed given the tool's simplicity.

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% (both page_size and start_cursor have descriptions). The description adds no extra parameter meaning beyond what the schema already 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 states the tool lists pages the integration has access to, using search with a page filter. This clearly distinguishes it from sibling tools like notion_get_page (single page by ID), notion_query_database (queries a specific database), and notion_search (general search).

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

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

The description implies use when you need to list all accessible pages, but does not explicitly state when not to use it or mention alternatives like notion_query_database for database-scoped queries.

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

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

Annotations are empty, so the description carries the burden of behavioral disclosure. It does not mention side effects (likely read-only), rate limits, authentication needs, or error conditions. However, 'query' suggests a read operation, and the description is consistent with that. It does not add rich behavioral context beyond the obvious, so a 3 is appropriate.

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 sentence of 12 words, which is concise and front-loaded. It efficiently communicates the core purpose. However, it could be slightly more structured (e.g., mentioning pagination or default page size) without adding much length, so it loses a point for not including important usage details.

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

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

Given the moderate complexity (5 params, nested objects), the description is minimal. It covers the basic purpose but lacks details on pagination (start_cursor, page_size defaults), response format (no output schema), and error handling. For a query tool with no annotations and no output schema, more context would be beneficial.

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 input schema already describes all parameters well. The description adds no extra meaning beyond summarizing the tool's purpose. Baseline 3 is correct because the schema does the heavy lifting; the description does not compensate with additional context.

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

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

The description clearly states the tool queries a Notion database with optional filters and sorts, and returns matching pages/rows. It uses a specific verb ('query') and resource ('Notion database'), and the optionality of filters/sorts is explicit. The tool name 'notion_query_database' is distinct from siblings like 'notion_search' or 'notion_list_pages', and the description reinforces this by specifying filters and sorts.

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 querying a database with filters and sorts, but does not explicitly state when to use this tool versus alternatives like 'notion_list_pages' or 'notion_search'. No guidance is given on when not to use it or what scenarios favor other tools. With siblings that perform similar functions, this lack of differentiation is a gap.

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?

No annotations are provided, so the description carries the full burden. It discloses it returns 'matching results with titles and IDs' but does not mention that it returns only top-level matching items (not nested content), or that it may not return full page content. Lacks behavioral details like rate limits or pagination 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?

The description is two sentences, front-loaded with purpose, and no wasted words. Could be slightly more precise but is acceptable.

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 search tool with 4 parameters and no output schema, the description is adequate but minimal. It does not explain pagination (despite having start_cursor) or return structure beyond titles and IDs. Without output schema, it should clarify what is returned per 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%, so the description does not need to repeat parameter details. The description adds no extra meaning beyond the schema, meeting the baseline. However, it could hint that 'filter' accepts only 'page' or 'database' (already in schema description).

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

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

The description clearly states the verb 'search' and the resources 'pages and databases', and mentions the output 'titles and IDs'. It distinguishes itself from siblings like 'notion_query_database' by searching across the workspace rather than a specific database.

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 it is the go-to for searching across the workspace but does not provide explicit when-to-use vs alternatives like 'notion_query_database' (which is for querying a specific database). No exclusions or prerequisites are mentioned.

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

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

No annotations are provided, so the description carries the full burden. It discloses rate limiting and the free nature, but does not specify other behaviors such as whether feedback is stored, how it is processed, or if it triggers any automated action. The behavioral transparency is adequate but not comprehensive.

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 highly concise with three sentences, each adding essential information. It is front-loaded with the purpose and efficiently covers use cases, guidelines, and limitations without 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 three parameters (one nested object) and no output schema, the description sufficiently covers purpose, usage guidelines, rate limits, and a privacy hint. The agent can use it correctly. A minor gap is not describing what happens after submission (e.g., confirmation), but it is not critical.

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

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

Input schema has 100% coverage with detailed descriptions for all parameters. The description adds value beyond the schema by including a privacy guideline (do not include end-user prompt verbatim) and rate limit context. This provides extra semantic meaning for the message 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 verb 'Send feedback' and the resource 'Pipeworx team', and enumerates specific use cases (bug reports, feature requests, missing data, praise). It distinguishes from sibling tools like ask_pipeworx which are for querying data.

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

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

The description explicitly tells when to use the tool (list of feedback types) and provides a key guideline to describe what was tried without including the end-user prompt verbatim. It also mentions rate limiting (5 messages per day) and that it is free. However, it does not explicitly state when not to use it or compare with siblings.

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

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

Annotations already indicate readOnlyHint=true, openWorldHint=true, destructiveHint=false. The description adds behavioral details: returns ranked opportunities with suggested trade direction and reasoning, and explains the monotonicity check. 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-structured paragraph. It front-loads the purpose, then details the two modes with examples. Every sentence adds value, no wasted words.

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

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

Given no output schema, the description adequately explains what the tool returns (ranked opportunities with suggested trade direction and reasoning). It covers both modes, usage, and input types, making it complete 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% (baseline 3). The description adds meaning by explaining that event mode accepts a slug or URL, and topic mode searches across related markets. Examples are provided.

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: finding arbitrage opportunities on Polymarket by checking monotonicity violations. It specifies two distinct modes (event and topic) and explains what each does, distinguishing it from sibling tools which are unrelated.

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

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

The description explicitly tells when to use each mode, with an example of a cross-event scenario where topic mode catches cases that event mode misses. It provides clear guidance on the input types for each mode.

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

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

Annotations already provide readOnlyHint, openWorldHint, and destructiveHint. The description adds value by detailing the algorithm: lognormal model from FRED and coinpaprika, grouping by asset, fetching price history once, computing model probability, ranking by |edge|, and returning top N with suggested trade direction. This goes beyond what annotations offer.

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

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

The description is a single paragraph of five sentences with no unnecessary words. It is front-loaded with the main purpose and each sentence adds value: purpose, model details, process, output, and use case. No fluff 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 no output schema, the description explains the return value (top N ranked by edge magnitude with suggested trade direction) and the algorithmic process. It covers the essential behavioral aspects for a discovery tool. However, it could be more explicit about the exact output fields or structure.

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

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

Schema coverage is 100% with parameter descriptions. The description adds meaning by explaining the algorithm context, which clarifies how parameters like limit, window, and min_edge_pp affect results (e.g., 'Top N edges to return after ranking'). This compensates well for any lack of detail in schema descriptions.

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

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

The description clearly states the tool's purpose: scanning high-volume Polymarket markets to find ones where Pipeworx data disagrees with market price. It specifies the resource (Polymarket markets), action (scan and return disagreements), and context (crypto-price bets with a lognormal model). This distinguishes it from siblings like polymarket_arbitrage and bet_research.

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

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

The description explicitly states the use case: 'what should I bet on today' and helps users discover opportunities without manual browsing. While it doesn't explicitly contrast with alternatives, the context implies when to use this tool versus researching specific markets or finding arbitrage.

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?

No annotations are provided, so the description carries full burden. It discloses that the tool can list all keys when key is omitted, which is a key behavioral trait. However, it doesn't mention what happens if key doesn't exist (error vs. null).

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 that front-load the primary action. Every word adds value; no wasted space.

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 retrieval tool with a single optional parameter and no output schema, the description is complete. It explains both modes of use (by key or listing). Minor gap: behavior on missing key.

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 single parameter 'key' is already described in the schema. The description adds no additional semantics beyond what the schema provides, so baseline 3 is appropriate.

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

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

The description clearly states the tool retrieves a memory by key or lists all memories when key is omitted. It distinguishes itself from sibling tools like 'remember' and 'forget' by focusing on retrieval.

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

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

The description explicitly tells when to use the tool ('to retrieve context you saved earlier') and implies when not to (omit key to list all). It contrasts with 'remember' and 'forget' via the tool names and 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?

No annotations exist, so description bears full burden. It details fan-out to SEC EDGAR, GDELT, USPTO in parallel, and mentions return structure including total_changes count and pipeworx:// URIs.

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 purpose, no redundancy. Every word contributes to 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?

Despite no output schema, the description covers return values and behavior. For a change monitoring tool with three parameters and clear fan-out logic, it 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% with good descriptions, but the description adds critical context: explains 'since' format (ISO date or relative like '7d'), and clarifies 'value' as ticker or CIK. Adds significant value beyond schema.

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

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

Description starts with 'What's new about an entity since a given point in time,' specifying the tool's purpose and distinguishing from siblings like entity_profile or compare_entities.

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

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

Explicitly states use cases: 'brief me on what happened with X' or change-monitoring workflows. Also explains 'since' parameter formats. Lacks explicit when-not-to-use but context is clear.

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

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

No annotations provided, so description carries full burden. Discloses memory persistence (authenticated vs 24-hour) and that it's session-based. Could add more about storage limits or overwrite behavior, but still strong.

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

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

Two sentences: first states purpose, second explains when and for whom. No wasted words, front-loaded with core action.

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 and simple key-value structure, description covers what agent needs: what it does, when to use, and behavioral differences. Lacks mention of overwrite behavior or value size limits, but sufficient for a simple memory 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 already provides clear descriptions for both parameters (key with examples, value with purpose). Description reinforces usage context without repeating schema, adding value by framing as session memory.

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

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

Clearly states the verb 'store' and resource 'key-value pair in session memory'. Distinguishes from siblings like 'recall' (retrieval) and 'forget' (deletion).

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

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

Explicitly says 'Use this to save intermediate findings, user preferences, or context across tool calls', and notes persistence differences for authenticated vs anonymous users.

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?

With no annotations, the description bears the burden. It discloses that the call resolves to canonical IDs and returns resource URIs, and notes it's a single-call replacement. It also mentions v1 limitations. This is sufficient for understanding 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?

The description is very concise: two sentences and a fragment, all front-loaded with the core purpose. Every sentence adds value, with no superfluous words.

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

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

Despite no output schema, the description lists the return fields (ticker, CIK, name, URIs). For a simple tool with two parameters, this is complete and covers all needed information for an agent to call it correctly.

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

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

The description adds concrete examples ('AAPL', '0000320193', 'Apple') and explains the format for 'value', while also clarifying that 'type' currently only supports 'company'. This enriches the schema descriptions significantly.

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

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

The description clearly states the tool resolves entities to canonical IDs, specifies supported type 'company', lists accepted input formats (ticker, CIK, name), and mentions output (ticker, CIK, name, URIs). It distinguishes from potential alternatives by noting it replaces 2-3 lookup calls.

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

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

The description explicitly states it replaces multiple lookup calls, implying when to use it. It also notes v1 only supports 'company', indicating when not to use. While no sibling tool name is given, the context is adequate 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?

No annotations are provided, so the description carries the full burden. It states v1 supports limited scope and returns specific outputs, but does not disclose limitations like rate limits, authentication requirements, or failure modes. Some behavioral context is given (e.g., replaces multiple calls), but more is needed for full transparency.

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

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

The description is concise, with 4 sentences that are front-loaded with the main purpose. Every sentence adds value: purpose, scope, output details, and efficiency benefit. 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 low complexity (one required parameter, no output schema), the description covers purpose, scope, output format (verdict types, citation), and comparison to alternatives. It could mention error handling for out-of-scope claims, but overall it is fairly complete for a simple tool.

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

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

The only parameter (claim) has 100% schema coverage, and the description adds meaning beyond the schema's description by providing examples and clarifying that it expects natural-language factual claims. This helps the agent understand the expected input format.

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

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

The description clearly states the tool fact-checks natural-language claims against authoritative sources, specifies the supported domain (company-financial claims via SEC EDGAR + XBRL), and lists the returned verdict types. It distinguishes from sequential agent calls by mentioning it replaces 4–6 of them.

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

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

The description tells when to use the tool (for fact-checking claims) and the supported domain, but does not explicitly mention when not to use it or alternative tools among siblings (e.g., ask_pipeworx, compare_entities). It implies it is a specialized replacement for multiple calls.

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