Lobsters

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

No annotations provided, so description carries full burden. It discloses that the tool selects the best source and fills arguments, but does not mention limitations like latency, data freshness, or potential errors. Adequate but could be more detailed.

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 short (3 sentences) with front-loaded action verb. Examples are helpful and concise. 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 simple input schema (single string parameter) and no output schema, description is complete enough. It explains the tool's abstraction and provides examples. Could mention return format (text) but 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?

Schema coverage is 100%, so description adds little beyond what the schema provides. The description explains that 'question' is a natural language request, which aligns with the schema's description. No additional semantic detail needed given full schema coverage.

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 answers natural language questions by selecting the best data source, with specific verb 'ask' and resource 'Pipeworx'. Examples differentiate it from sibling tools like 'get_story' or 'get_hottest' which are data retrieval tools requiring structured parameters.

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 explains when to use: when you have a natural language question and want the system to handle tool selection. It implies alternatives (browsing tools/learning schemas) but does not explicitly exclude scenarios where direct tool usage might be 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?

Discloses behavior beyond annotations: resolves market, classifies bet type, fans out to relevant packs, and returns comparison. Annotations already indicate readOnly and openWorld, which aligns. 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?

Description is somewhat lengthy but front-loaded with purpose. Every sentence adds information; no fluff. Could be slightly shorter, but earned its length given the tool's complexity.

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

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

Given no output schema, description fully explains return values (evidence packet, comparison) and process (fan-out, classification). Covers inputs, behavior, and use cases. No gaps for this complex tool.

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

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

Schema coverage is 100%, but description adds value by providing examples for 'market' and explaining 'depth' options (quick=2-3 sources, thorough=full fan-out). This clarifies usage beyond the schema's enum and type 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 researches a Polymarket bet by pulling Pipeworx data, with specific inputs (slug, URL, question) and outputs (evidence packet, comparison). It distinguishes from siblings by noting it is the core demo product that avoids manual pack discovery.

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 gives example queries ('should I bet on X?', 'what does the data say?', 'is there edge?'). Does not explicitly state when not to use, but implies it's for bet-specific research, not general data queries (sibling ask_pipeworx).

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 describes the tool as a read operation (comparing and returning data), but does not disclose any behavioral traits such as data freshness, authentication requirements, or what happens if an entity is not found. The description is adequate but lacks explicit behavioral details beyond the core functionality.

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 and well-structured: it opens with the core purpose, then details each entity type, mentions the return format, and concludes with the efficiency benefit. Every sentence adds value, and there is 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?

There is no output schema, so the description should cover return values. It mentions 'paired data + pipeworx:// resource URIs' but does not specify the exact structure or format of the paired data. For company type, metrics are listed, but completeness (e.g., whether all metrics always exist) is not addressed. The description is adequate for basic understanding but lacks full detail on output shape and edge cases.

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

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

The input schema has 100% description coverage for both parameters. The description adds meaning beyond the schema by explaining that 'type' restricts the entity type and that 'values' should be tickers/CIKs for company or drug names, with constraints on the count (2–5). This augments the schema effectively.

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

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

The description clearly states the tool's action: 'Compare 2–5 entities side by side in one call.' It specifies the two entity types (company, drug) and the data fields for each. It distinguishes from siblings by noting it replaces 8–15 sequential agent 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 when to use the tool: for comparing 2–5 entities in one call. It implies that for single entity retrieval or sequential calls, alternative approaches are less efficient. However, it does not explicitly state when not to use it or provide specific 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?

With no annotations provided, the description carries the full burden. It accurately discloses the tool's behavior: it searches by description, returns relevant tools, and suggests calling it first. However, it doesn't detail the return format or any limitations beyond the parameter hints.

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: three sentences that front-load the core purpose, then the action, then the usage guideline. 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 parameters, no output schema, no nested objects), the description is complete. It explains the tool's purpose, when to use it, and how to use it. No additional information is needed for correct invocation.

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

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

The input schema already has 100% coverage with descriptions for both parameters. The description adds no additional meaning beyond what the schema provides, so a baseline score of 3 is appropriate.

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

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

The description clearly states the tool's purpose: searching the Pipeworx tool catalog by describing what you need, and returning relevant tools with names and descriptions. It uses a specific verb-resource combination ('search the Pipeworx tool catalog') and distinguishes itself from siblings by being a discovery/search tool among many others that are more specific.

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: 'Call this FIRST when you have 500+ tools available and need to find the right ones for your task.' It provides a clear usage guideline and implicitly suggests that other sibling tools are for more specific actions.

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 provided, the description carries the full transparency burden. It discloses that the tool returns 'pipeworx:// citation URIs' and replaces 10-15 sequential calls. However, it does not mention idempotency, rate limits, or exact response structure, which would improve transparency further. The information provided is still good and does not contradict any annotations (none 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 very concise with three sentences, each serving a distinct purpose: (1) overall intent, (2) what the company profile includes, (3) alternative for federal contracts. No unnecessary words, and the key information is front-loaded.

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

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

Given the tool's complexity (replacing 10-15 calls) and the lack of an output schema, the description adequately explains the types of data included and mentions citation URIs. It could be improved by hinting at the response structure, but the provided context is sufficient for an AI agent to understand what to expect.

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

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

The input schema has 100% description coverage, so the description adds minimal new parameter meaning beyond what the schema already states. It reinforces that 'type' is currently limited to 'company' and 'value' accepts ticker/CIK, but this does not add significant value over the schema itself.

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

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

The description clearly states the tool's purpose as 'Full profile of an entity across every relevant Pipeworx pack in one call' and lists specific data types included for 'company' entities. It distinguishes itself from the sibling resolve_entity (for names) and usa_recipient_profile (for federal contracts), making the scope 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 use 'usa_recipient_profile directly' for federal contracts and refers to 'resolve_entity' for name-based lookups. This provides clear when-to-use and when-not-to-use guidance, plus explicit 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?

No annotations are provided, so the description must fully disclose behavior. It only states deletion by key, but does not mention whether deletion is permanent, if there are side effects, or any error states (e.g., key 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, directly states the action and what is deleted. 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 1-parameter tool with no output schema, the description covers the basic purpose but lacks behavioral details (permanence, errors) that would be helpful given no annotations.

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

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

The schema already describes the 'key' parameter with 100% coverage. The description adds no additional meaning 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 uses a specific verb ('Delete') and resource ('stored memory by key'), clearly distinguishing it from siblings like 'remember' (store) and 'recall' (retrieve).

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 deletion is done by key, but does not provide guidance on when to use this tool vs alternatives like 'remember' or 'recall', or any prerequisites like existence of the key.

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 carries the full burden. It states it returns 'hottest (front page) stories', which implies read-only behavior, but lacks details on pagination, limits, or authentication needs. Adequate but minimal.

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, concise sentence that front-loads the purpose. 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 (no parameters, no output schema), the description is minimally adequate. However, it does not mention return format or behavior (e.g., ordering, caching). A 3 is appropriate.

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

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

The input schema has 0 parameters and 100% coverage, so no param info is needed. The description adds no parameter semantics, but baseline is 4 due to high coverage and no params.

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 'Get' and the resource 'hottest (front page) stories on Lobsters'. It is specific and distinguishes from sibling tools like get_newest and get_story.

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 fetching front-page stories but does not provide explicit guidance on when to use this tool vs alternatives (e.g., get_newest for recent stories). No when-not-to-use or exclusions are stated.

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 full burden. It indicates a read operation (no side effects) but does not disclose pagination, rate limits, or return format. This is adequate for a simple tool with no parameters.

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, concise sentence that gets straight to the point. It could be slightly more descriptive but is appropriately short for a tool with no parameters.

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 no parameters and no output schema, the description provides sufficient information to understand its purpose. However, it lacks details on the response structure or sorting, which might be helpful.

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 0 parameters and 100% coverage, so no parameter info is needed. The description adds no parameter semantics, which is acceptable given no parameters exist.

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 the newest stories on Lobsters, with a specific verb ('Get') and resource ('newest stories'). It is distinct from siblings like get_hottest or get_story, which retrieve different subsets of stories.

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 fetching newest stories but provides no guidance on when to use this versus alternatives like get_hottest or get_story. 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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It indicates a read operation returning story+comments, but does not mention any rate limits, authentication needs, or whether comments are nested or flat. The behavior is generally clear but not exhaustive.

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

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

The description is a single, front-loaded sentence with no wasted words. It conveys the core purpose efficiently.

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

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

Given the simple tool (1 param, no output schema, no nested objects), the description is complete enough. It explains what is returned (story and comments) and how to identify it (short ID). No further details are needed for basic 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%, so the description does not need to add much. It restates the schema's description of the short_id parameter but adds the context of 'from the Lobsters URL' and gives an example format, which provides minor additional clarity.

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

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

The description clearly states it retrieves a single story and its comments, specifying the resource (Lobsters story) and the identifier (short ID). This distinguishes it from siblings like get_hottest or get_newest which return lists, and get_tag which filters by tag.

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 have a specific short ID, which is clear context. However, it does not explicitly state when not to use it or mention alternatives for other use cases.

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 carries full burden for behavioral transparency. It does not disclose any behavioral traits such as pagination, rate limiting, or result format. The description is minimal and lacks details beyond the basic operation.

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, concise and front-loaded with the core action. It is appropriately sized for a simple tool with one parameter, with no wasted words.

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

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

Given the simplicity (1 parameter, no output schema, no nested objects), the description is somewhat adequate but lacks completeness. It does not explain what 'stories' means, the format of results, or any filtering options, which could be helpful for an agent.

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

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

Schema description coverage is 100%, so the description need not add much. It provides examples for the tag parameter, reinforcing the schema. However, it doesn't add new semantic information beyond what the schema already provides, earning a 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 the tool retrieves stories for a Lobsters tag, with a specific verb 'Get' and resource 'stories for a specific Lobsters tag'. It provides examples of tag values, making the purpose clear. However, it does not distinguish from siblings like get_hottest or get_newest, which also retrieve stories.

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 does not provide guidance on when to use this tool versus alternatives. Sibling tools like get_hottest and get_newest also retrieve stories, but the description offers no differentiation or 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?

With no annotations, the description carries the full burden. It discloses the rate limit and that it is free, but does not discuss what happens after submission (e.g., no guarantee of response) or any side effects. For a feedback tool, the behavior is relatively simple, 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 extremely concise, with two sentences and a short phrase. It front-loads the purpose ('Send feedback') and uses clear, direct language. 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 and no annotations, the description covers purpose, usage guidelines, and rate limiting. It could mention that feedback is sent asynchronously or that no confirmation is given, but it is largely complete for a simple feedback 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 valuable guidance beyond the schema: 'Describe what you tried in terms of Pipeworx tools/data — do not include the end-user's prompt verbatim.' This helps agents construct proper messages.

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: 'Send feedback to the Pipeworx team.' It lists specific use cases (bug reports, feature requests, missing data, praise) that distinguish it from sibling tools like ask_pipeworx and compare_entities, which are for data 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 (for feedback types) and what to include/exclude: 'Describe what you tried in terms of Pipeworx tools/data — do not include the end-user's prompt verbatim.' It also mentions the rate limit of 5 messages per day, setting expectations.

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

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

Annotations already indicate readOnlyHint=true and destructiveHint=false, aligning with the description's mention of searching and returning opportunities. The description adds valuable behavioral context: it reveals that cross-event mode searches across separate events and groups related markets, and that the output includes 'suggested trade direction + reasoning'. 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 well-structured paragraph with clear distinction between modes, an explanatory note on cross-event rationale, and a summary of the output. It is not overly verbose, though it 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 that the input schema covers both parameters with good descriptions, annotations are present, and the description explains the output format (ranked opportunities with reasoning), the tool is fully specified for correct invocation. No output schema is present, but the description compensates adequately.

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

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

The input schema already provides clear descriptions for both parameters, covering 100% of schema coverage. The tool description does not add new semantic information about the parameters themselves beyond what the schema provides, so a baseline score of 3 is appropriate.

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

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

The description clearly states the tool's purpose: 'Find arbitrage opportunities on Polymarket by checking for monotonicity violations across related markets.' It then details two modes ('event' and 'topic'), explaining their specific use cases. This level of detail clearly distinguishes it from sibling tools like 'bet_research' or 'polymarket_edges'.

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 the two modes and provides examples of when to use each, including the rationale for cross-event mode (catches cases where single-event mode misses). It does not explicitly state when not to use the tool, but the guidance is clear enough for appropriate selection.

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

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

Description explains the internal process (groups by asset, fetches price history once, computes probability, ranks by |edge|). This adds behavioral context beyond annotations which indicate read-only and non-destructive. No contradiction with annotations.

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

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

Description is informative but somewhat long; front-loaded with primary purpose. Could be slightly more concise, 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 states returns top N with suggested trade direction. Covers the key output expectations given the tool's purpose and 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?

All three parameters have descriptions in the schema (100% coverage). The description only lightly reiterates limit ('returns top N') and window ('volume window'). Does not add significant new meaning beyond schema.

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

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

Description clearly states the tool scans top Polymarket markets, identifies where Pipeworz data disagrees with market price, and returns opportunities. It specifies the model (lognormal from FRED + coinpaprika) and the use case, distinguishing it from siblings.

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

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

Explicitly says 'Built for the what should I bet on today question' and that it avoids paging through hundreds of markets. This gives strong context for when to use, though it doesn't explicitly mention when not to use or alternative tools.

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

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

No annotations are provided, so the description carries full burden. It correctly indicates that omitting the key lists all stored memories, which is a key behavioral trait. It also implies that retrieval is non-destructive and safe, but could be more explicit about whether repeated calls have side effects.

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

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

Two concise sentences, front-loaded with the primary action, no wasted words. Each sentence adds necessary information.

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

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

Given the low complexity (1 optional param, no output schema), the description is nearly complete. It explains both use cases and provides context. Could mention return format, but not required 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 description coverage is 100% with a single parameter ('key') already well-described in schema. The description adds value by clarifying the behavior when 'key' is omitted (list all), which is not explicit in the schema.

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

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

The description clearly states the tool's purpose: retrieve a memory by key or list all memories if key is omitted. It uses a specific verb ('retrieve') and resource ('memory by key'), distinguishing it from siblings like 'remember' (store) and 'forget' (delete).

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

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

The description provides clear usage context: 'Use this to retrieve context you saved earlier in the session or in previous sessions.' It implies when to use (when you need previously saved context) but does not explicitly mention when not to use 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?

No annotations exist, so the description carries full behavioral disclosure. It reveals that the tool fans out to three external sources in parallel, accepts two date formats, and returns structured changes with counts and URIs. It omits potential side effects, auth needs, or rate limits, but the disclosed behavior is adequate for safe invocation.

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 (five sentences) and well-structured. It opens with the core purpose, then details parameters and behavior, and ends with use cases. No redundant or extraneous information.

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

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

Given the tool's complexity (multiple sources, parallel execution, two date formats, structured output), the description covers inputs, processing, and return values comprehensively. No output schema exists, but the description mentions fields ('structured changes', 'total_changes', 'pipeworx:// URIs') sufficiently for an agent to use the tool.

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

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

Schema coverage is 100%, providing baseline clarity. The description adds significant value by explaining the 'since' parameter with concrete examples ('7d', '30d', '3m', '1y', ISO dates) and clarifying that 'value' accepts tickers or CIK strings. This enriches the schema beyond its minimal 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: retrieving what's new about an entity since a given time. It specifies the supported entity type ('company') and the data sources polled (SEC EDGAR, GDELT, USPTO), making the action and scope 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 recommends use for 'brief me on what happened with X' or change-monitoring workflows, providing clear context. However, it does not contrast with sibling tools (e.g., 'entity_profile', 'get_hottest') or state when not to use it, slightly limiting differentiation.

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

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

The description discloses persistence behavior: authenticated users get persistent memory, anonymous sessions last 24 hours. No annotations are provided, so the description carries the full burden, and it does so adequately. It does not mention any destructive actions or rate limits, but none are relevant.

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: first explains purpose, second suggests use cases, third explains persistence. 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 and simple input, the description is complete enough. It covers purpose, usage, and persistence. Could add note about overwriting existing keys, but not essential.

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%, with clear parameter descriptions for key and value. The description adds context about usage (e.g., example keys like 'subject_property') beyond the schema, which is helpful but not extensive.

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 stores a key-value pair in session memory, with specific examples of use cases (saving findings, preferences, context). This distinguishes it from siblings like recall (retrieve) and forget (remove).

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 save intermediate findings, user preferences, or context across tool calls). However, it does not explicitly mention when not to use it or provide alternatives beyond the implied contrast with recall/forget.

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 full disclosure burden. It clarifies the tool is read-only (resolve, returns), specifies version (v1) and supported type (company), and details return values (ticker, CIK, name, pipeworx URIs). It lacks explicit mention of error handling or rate limits, but covers core behavior well.

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 (3 sentences) and front-loaded with the main purpose. Each sentence provides distinct information: action and scope, input examples and version, return details, and efficiency gain. 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?

For a simple tool (2 parameters, no output schema), the description is complete. It explains inputs, outputs, and use case. The agent can confidently invoke it based on this text alone.

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 descriptive fields. The description adds value by providing concrete examples (AAPL, 0000320193, Apple) and explaining the return purpose (stable citation via pipeworx URIs), going beyond basic schema definitions.

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

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

The description clearly states the tool's action: 'Resolve an entity to canonical IDs across Pipeworx data sources'. It specifies the resource (entity types like company) and distinguishes itself from siblings by noting it 'Replaces 2–3 lookup calls', indicating efficiency over separate sibling lookups.

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

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

The description provides clear context for use: 'in a single call' and 'Replaces 2–3 lookup calls', implying it is the preferred tool for entity resolution when multiple sources are involved. However, it does not explicitly list when not to use it or mention alternative sibling tools, though sibling names suggest different functions.

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 full burden. It discloses return values (verdict, structured form, citation, delta) and version limitations (v1, specific domains). However, it does not state whether the tool is read-only or has side effects, nor does it detail error handling or 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?

Three sentences efficiently convey purpose, domain, return values, and efficiency. No redundant words; front-loaded with key information.

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

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

The description covers purpose, supported domain, sources, and output for a single-parameter tool. It lacks details about error handling or limitations of the v1 implementation, but these are minor omissions 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?

The input schema has 100% coverage with a description for 'claim' and examples. The tool description adds significant context: it restricts valid claims to company-financial metrics for US public companies and specifies the data source, which helps the agent form appropriate queries.

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: fact-checking natural-language claims against authoritative sources. It specifies the supported domain (company-financial claims for US public companies) and the sources (SEC EDGAR + XBRL), distinguishing it from sibling tools like ask_pipeworx or compare_entities.

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

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

The description implies usage for fact-checking financial claims and mentions it replaces multiple agent steps, but does not explicitly state when not to use it or compare to siblings. The context is clear enough given the sibling names.

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