Lemmy

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds that the tool routes the question to one of 1,423+ tools, fills arguments, and returns structured answers with citation URIs. This discloses the meta-tool behavior and output format, going beyond annotations.

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

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

The description is a single dense paragraph but is well-organized, starting with a strong directive. Every sentence adds value, though it could benefit from bullet points or a shorter form. It is front-loaded with the key preference statement.

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 single required parameter and no output schema, the description fully covers usage: it explains what the tool does, when to use it, and what the output looks like (structured answer with citations). No gaps remain.

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

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

The only parameter 'question' has 100% schema coverage. The description supplements it by specifying the types of questions suitable (factual, real-world entities, etc.), which adds meaning beyond the schema's generic 'natural language' description.

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

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

The description clearly states the tool's purpose: answering factual questions about real-world data from authoritative sources. It differentiates from web search by explicitly saying 'PREFER OVER WEB SEARCH' and lists specific domains like SEC filings, FDA drug data, etc. This is a specific verb+resource combination with sibling differentiation.

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

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

The description provides explicit when-to-use guidance: for factual questions about current or historical data, and when the user asks 'what is', 'look up', etc. It also contrasts with web search, making the decision boundary clear. Examples are given, such as 'current US unemployment rate'.

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

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

Annotations already indicate readOnlyHint=true, openWorldHint=true, destructiveHint=false. The description adds context about fanning out to packs based on classification and returning a comparison, which goes beyond annotations without contradiction.

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

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

The description is slightly long (4 sentences) but front-loaded with action and input. The extra details (classification list) are relevant and not wasteful, justifying the length.

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

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

Given the complexity (2 params, no output schema, annotations present), the description fully covers inputs, behavior, and output. It explains fan-out logic and comparison, making it complete for the tool's purpose.

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 meaning: explains 'depth' differences (quick vs thorough) and 'market' format acceptance. This adds value beyond the schema.

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

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

The description clearly states the tool researches a Polymarket bet by pulling Pipeworx data, specifying inputs (slug, URL, question text) and outputs (evidence packet, comparison). It distinguishes itself from sibling tools by being the core demo product for 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 provides clear use cases ('should I bet on X?', 'what does the data say?', 'is there edge?') and hints at superiority over using individual packs, but does not explicitly state when not to use it or mention alternatives.

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

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

Annotations already indicate readOnlyHint=true, openWorldHint=true, and destructiveHint=false, covering safety. The description adds no additional behavioral context such as pagination, filtering behavior, or result format.

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

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

Extremely concise but under-specified. A single word is not informative; substance is missing.

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 8 parameters, no output schema, and no parameter descriptions, the tool is severely incomplete. An agent cannot determine how to invoke it correctly or interpret results.

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

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

Schema description coverage is 0%, meaning no parameter descriptions in the schema. The description also provides no information about parameters like 'page', 'sort', 'limit', or 'post_id' beyond their names.

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

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

The description is a single word 'Comments.', which is a tautology of the tool name. It lacks a verb and does not specify what action the tool performs or what resource it acts upon.

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

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

No guidance is provided on when to use this tool versus siblings like 'post', 'posts', or 'search'. The description offers no context for appropriate usage.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds that it lists communities, which is consistent. No further behavioral details are provided, but annotations cover safety.

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

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

The description is extremely concise (two words) and front-loaded. While it is efficient, it may be too minimal for a tool with five undocumented 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 lack of output schema, zero parameter documentation, and no usage guidance, the description is insufficient for an agent to use the tool effectively.

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

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

With 0% schema description coverage and no parameter explanations in the description, the agent has no insight into the meaning or usage of the five parameters (page, sort, limit, type_, instance).

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

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

The description 'List communities' clearly states the verb 'list' and resource 'communities'. It is specific and unambiguous, but does not differentiate from the sibling tool 'community' (singular).

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

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

No guidance on when to use this tool versus alternatives like 'community'. There is no context about prerequisites, exclusions, or appropriate scenarios.

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

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

Annotations already indicate readOnlyHint=true (read operation) and destructiveHint=false. The description adds minimal behavioral context beyond 'metadata', not explaining what metadata includes or if it returns a single community.

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

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

The description is extremely short (two words) but is under-specified rather than concise. It sacrifices necessary information for brevity.

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

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

The tool has 2 parameters and no output schema, but the description is insufficient. It does not explain what the tool returns, how to use it, or any context about community metadata.

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

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

With 0% schema description coverage, the description must compensate but provides no explanation for the parameters 'instance' and 'name_or_id'. Their meaning and usage are entirely unclear.

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 'Community metadata.' is a vague noun phrase that does not specify a verb like 'get' or 'retrieve', making it unclear what action the tool performs. It does not distinguish from the sibling tool 'communities', which could list communities.

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

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

No usage guidelines are provided. The description fails to indicate when to use this tool, when not to use it, or mention any alternative tools.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. Description adds specific data sources (SEC EDGAR/XBRL for companies, FAERS for drugs) and mentions return of paired data with citation URIs. 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?

Single paragraph with front-loaded purpose, followed by use-case patterns, data details, and efficiency benefit. No unnecessary words, well-structured for quick parsing.

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, description only vaguely mentions 'paired data + pipeworx:// citation URIs'. While annotations cover read-only nature, the output format is underspecified. For a compare tool, more detail on return structure 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%, and description provides concrete examples for both parameters (e.g., tickers like AAPL, MSFT; drug names like ozempic). This adds meaningful context beyond the schema's enum and array 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: comparing 2-5 companies or drugs side by side. It specifies the data pulled for each type (financials for companies, adverse events/approvals/trials for drugs) and distinguishes it from siblings by noting it replaces many sequential calls.

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

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

Explicitly lists trigger phrases ('compare X and Y', 'X vs Y', etc.) and contexts (tables, rankings). Does not explicitly state when not to use, but the efficiency benefit implies alternatives involve multiple single-entity calls. Good practical guidance.

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

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

Discloses that the tool returns top-N relevant tools with names and descriptions, consistent with readOnlyHint=true. Adds behavioral context about being a discovery tool, but could mention that it's non-destructive and read-only explicitly.

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

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

Front-loaded with purpose and usage, but the list of domains is somewhat lengthy. Overall efficient and well-structured.

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

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

Covers purpose, usage, parameter hints, and return value (top-N relevant tools). For a simple discovery tool with no output schema, it provides adequate context.

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

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

Schema coverage is 100% with descriptions for both parameters. The description adds no new meaning beyond the schema, so it meets baseline but does not enhance parameter understanding.

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 with specific verb 'Find' and resource 'tools', and distinguishes it from sibling tools by advising 'Call this FIRST' when exploring options.

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

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

Provides explicit when-to-use guidance ('Use when you need to browse...') and strategic advice ('Call this FIRST'), but does not include explicit when-not-to-use scenarios.

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

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

Annotations indicate read-only and non-destructive; description adds that it returns SEC filings, financials, patents, news, LEI with citation URIs, and input constraints.

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 paragraph front-loaded with purpose, then usage, then returns. Every sentence adds value, 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?

No output schema, but description lists specific return types and input constraints, making the tool fully understandable.

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

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

Schema already describes both parameters with 100% coverage; description adds usage context (only 'company' type, ticker/CIK vs name) but does not go beyond schema details.

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 fetches comprehensive company information in one call, listing specific use cases (e.g., 'tell me about X') and distinguishing itself from siblings by replacing multiple tools.

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

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

Explicitly states when to use (user asks for company info) and when not (if only a name, use resolve_entity first), with concrete examples.

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 set destructiveHint=true, but description adds context about clearing sensitive data and pairing with other tools. 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?

Two sentences, no unnecessary words, highly concise while conveying all 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 tool's simplicity (1 param, no output schema, annotations present), the description is complete. It covers purpose, usage guidelines, and relationships with siblings.

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

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

Schema coverage is 100% with a single parameter 'key' described as 'Memory key to delete'. Description does not add additional semantic detail 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 'Delete a previously stored memory by key' with a specific verb and resource. It distinguishes from siblings like 'remember' and 'recall' as the delete counterpart.

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

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

Explicitly states when to use: 'when context is stale, the task is done, or you want to clear sensitive data'. Also suggests pairing with 'remember' and 'recall'.

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 explains that feedback is read by the team daily and influences roadmap, and states the rate limit of 5 per identifier per day. It does not contradict annotations, and adds meaningful behavioral context beyond the structured fields.

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

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

The description is a single concise paragraph with logical flow: purpose, use cases, how to structure feedback, and constraints. It's slightly dense but efficient, with no redundant 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 simplicity (sending feedback) and that the schema covers all parameters with descriptions, the description provides complete context: when, how, and what not to do. No output schema needed as the tool is a one-way action.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds extra value by elaborating on the enum values (e.g., bug vs feature) and providing guidelines on how to write the message (be specific, reference tools/packs, 2000 char limit). This enhances understanding beyond the schema.

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

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

The description clearly states the tool's purpose: sending feedback to the Pipeworx team about bugs, feature requests, data gaps, or praise. It distinctly differentiates from sibling tools like 'ask_pipeworx' or 'search' which are for queries, not feedback.

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

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

The description provides explicit when-to-use conditions (bug, feature/data_gap, praise) and what not to do (don't paste end-user prompt). It also mentions rate limits and that the tool is free, giving clear operational context.

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

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

Annotations already declare readOnlyHint, openWorldHint, and destructiveHint. Description adds behavioral context: tool searches, groups, and ranks opportunities. Does not contradict annotations.

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

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

Well-structured with mode breakdown and example. Each sentence adds value, though slightly verbose. 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?

No output schema, but description states returns ranked opportunities with reasoning. Covers main functionality and modes. Missing minor details like error handling or result format, but overall sufficient.

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

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

Schema coverage is 100%. Description adds meaning by explaining each parameter's role in the respective mode (e.g., slug/URL for event, seed question for topic).

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

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

Clearly states the tool identifies arbitrage opportunities via monotonicity violations. Describes two distinct modes (event and topic), making it specific and distinguishable from siblings like 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?

Explicitly explains when to use each mode, including a concrete example of when cross-event mode is necessary. Provides clear context for choosing between event and topic parameters.

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

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

Annotations (readOnlyHint=true, openWorldHint=true, destructiveHint=false) indicate safe read-only behavior. The description adds value by detailing the algorithm: scanning top markets, grouping by asset, fetching price history once, computing model probability, and ranking by |edge|. This goes beyond annotations, though it doesn't cover performance or rate limits. No contradiction exists.

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 six sentences, each serving a distinct purpose: purpose, model details, process, output, and use case. It is front-loaded with the core action and avoids redundancy. No filler or unnecessary technical jargon beyond what is needed.

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 what is returned ('top N ranked by edge magnitude with suggested trade direction') and how the tool works algorithmically. It covers input, process, and output sufficiently. However, exact output fields (e.g., market name, probability, edge value) are not specified, which could improve clarity for agent invocation.

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

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

Schema coverage is 100% with descriptions for all three parameters. The description reinforces defaults (limit default 10, max 25; window default 1wk; min_edge_pp default 0.5) and explains their role in ranking. This adds practical context beyond the schema, especially for the limit parameter's constraints.

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

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

The description clearly states the tool scans high-volume Polymarket markets, identifies where Pipeworx data disagrees with market price, and returns top opportunities ranked by edge magnitude with trade direction. It specifies the model (lognormal from FRED + coinpaprika) and scope (crypto-price bets). This is a specific verb-resource combination, and while sibling tools exist, the description distinguishes it as an opportunity discovery tool for the 'what should I bet on today' question.

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 frames the tool as answering 'what should I bet on today' and notes it avoids paging through hundreds of markets. This gives clear when-to-use context. However, it does not explicitly state when not to use it (e.g., for deep individual market analysis) or reference alternatives like bet_research. The guidance is strong but could be more comprehensive.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds only that it retrieves by ID, with no mention of return format, pagination, or side effects. With openWorldHint=true, more context would help.

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

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

The description is extremely short but not optimally informative. It could be expanded slightly to cover parameters without becoming verbose.

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 two parameters, the description is too sparse. It omits parameter details and return information, making it inadequate for confident invocation.

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

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

Schema description coverage is 0%. The description implies 'id' is the identifier but does not explain the 'instance' parameter at all, leaving the agent with incomplete info.

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 'Single post by id.' clearly identifies the tool as retrieving one post by its ID, which differentiates from the sibling tool 'posts' (plural).

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?

Usage is implied by the name and description: use for a single post, 'posts' for multiple. However, no explicit when-to-use or alternatives are provided.

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

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

Annotations (readOnlyHint, destructiveHint, openWorldHint) already indicate safe, read-only, open-world behavior, but the description adds no additional behavioral context such as pagination, rate limits, or result variability. The description contributes no value beyond the annotations.

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

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

The description is extremely concise (two words) but at the expense of essential information. It fails to earn its place by providing any substantive guidance beyond the name.

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 6 parameters, no output schema, and no behavioral details, the description is completely inadequate. An agent cannot determine how to effectively use this tool for different filtering needs (e.g., sorting, community, type) without external knowledge.

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 50% (3 of 6 parameters have descriptions), but the tool description does not add any parameter-level meaning. It does not explain how parameters like 'page', 'limit', or 'instance' affect the output, nor does it compensate for the undocumented parameters.

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

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

The description 'List posts' is a minimal verb+resource but lacks any specificity about the scope, filtering, or relation to sibling tools like 'post', 'comments', or 'communities'. It does not clarify whether it lists all posts or has implicit filters, making it vague and non-distinctive.

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 'posts' versus alternatives such as 'post', 'comments', or 'search'. There is no mention of prerequisites, context, or exclusions, leaving the agent without decision-making support.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the description adds moderate value by mentioning scope ('Scoped to your identifier') and the pairing pattern. No contradictions. The description does not elaborate on behavior beyond what annotations imply, but it does not need to for this simple 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 concise, consisting of three well-structured sentences. The core function is front-loaded in the first sentence, and each subsequent sentence adds contextual value without redundancy. Every sentence earns its place.

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

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

Given the tool's simplicity (one optional parameter, no output schema, clear annotations), the description is highly complete. It covers retrieval, listing, scoping, and pairing with related tools. No additional information is needed for an agent to invoke it correctly.

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

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

The input schema has 100% coverage, describing the single parameter 'key' as 'Memory key to retrieve (omit to list all keys)'. The description adds no further semantic detail 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 two functions: retrieving a value by key or listing all keys when omitted. It uses specific verbs ('retrieve', 'list') and explicitly mentions the related resources ('value previously saved via remember', 'all saved keys'). This distinguishes it clearly from sibling tools like 'remember' (save) 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 explicit usage guidance: 'Use to look up context the agent stored earlier... without re-deriving it from scratch.' It also explains scoping ('Scoped to your identifier') and suggests pairing with 'remember' and 'forget'. While it doesn't explicitly state when not to use, the context is clear enough 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?

Adds beyond annotations: explains parallel fan-out to SEC EDGAR, GDELT, USPTO and output structure (changes, count, URIs). Does not disclose potential performance or rate limits.

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

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

Single paragraph is front-loaded with purpose and usage, but packs many details efficiently. Minor structural improvement possible (e.g., bullet points), but still 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 full schema coverage and annotations, description completes the picture: explains output fields and data sources. No output schema, but description covers return values sufficiently.

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

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

All parameters have schema descriptions, and tool description adds context: 'since' examples (ISO date, relative shorthand), 'value' formats (ticker, CIK), 'type' limitation. Adds 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 clearly states verb phrase 'what's new with a company' and provides multiple example user queries, distinguishing from static profile tools like entity_profile.

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

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

Includes explicit use cases ('use when user asks...') and explains fan-out to multiple sources, but does not explicitly state when not to use or mention alternatives.

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

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

The description adds behavioral context beyond annotations: it explains data persistence ('scoped by your identifier'), retention limits ('authenticated users get persistent memory; anonymous sessions retain memory for 24 hours'). Annotations already indicate a write operation (readOnlyHint=false) and non-destructive (destructiveHint=false). No contradiction.

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

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

The description is concise (3 sentences) and front-loaded with the primary purpose. Every sentence adds value—purpose, usage, and behavior. No wasted words.

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

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

Given the tool's simplicity (2 required params, no output schema), the description is mostly complete. It covers usage, storage semantics, and referenced sibling tools. The only missing detail is the return value format, but for a store operation 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 descriptions for both parameters. The description adds semantic value by explaining the key-value pair storage model and scope, which is not explicit in the schema alone. Baseline 3, plus extra context makes it 4.

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: 'Save data the agent will need to reuse later' with specific examples (resolved ticker, target address, user preference). It distinguishes from sibling tools recall and forget by mentioning them as complementary actions.

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

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

The description explicitly says when to use this tool ('when you discover something worth carrying forward') and how to use it ('so you don't have to look it up again'). It also pairs it with recall and forget. However, it does not explicitly state when not to use it, but the context is clear.

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

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

Annotations already declare the tool as read-only and non-destructive. The description adds value by explaining that the tool returns IDs plus 'pipeworx:// citation URIs' and notes it replaces multiple lookup calls, giving the agent a clear picture of behavior beyond what annotations provide.

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

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

The description is concise yet comprehensive: three sentences covering purpose, examples, usage instructions, and return value. No redundant information; every sentence serves a purpose. The structure front-loads the core function and then provides supporting 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?

Despite having no output schema, the description sufficiently covers return values (IDs + URIs) and usage context. With two simple parameters and rich annotations (readOnlyHint, openWorldHint, destructiveHint), the description fills all gaps an agent needs to invoke this tool correctly.

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

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

The input schema has 100% description coverage, so baseline is 3. The description enhances understanding with concrete examples (e.g., 'Apple' → AAPL/CIK) and clarifies the expected format for the 'value' parameter (ticker, CIK, or name for company; brand/generic for drug). This adds meaningful semantic guidance beyond the schema.

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

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

The description clearly states the action ('Look up the canonical/official identifier'), the target entities (company or drug), and the specific ID systems (CIK, ticker, RxCUI, LEI) with concrete examples. It also distinguishes itself as a prerequisite tool for other tools needing official identifiers, which differentiates it from sibling tools like 'search' or 'entity_profile'.

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

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

The description explicitly advises to use this tool 'BEFORE calling other tools that need official identifiers' and provides scenarios (SEC, stock data, FDA, LEI). It does not explicitly mention when to avoid using it or name alternative tools, but the context is clear enough for an AI agent to decide.

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

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

Annotations already declare readOnlyHint and destructiveHint, so safety is clear. The description adds nothing beyond that but does not contradict annotations.

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

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

The description is too short to be useful. It says nothing substantive, so the conciseness is due to under-specification rather than efficient design.

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

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

Given the complexity (7 parameters, no output schema, low schema coverage), the description is completely inadequate. An agent would have no guidance on how to correctly invoke this 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?

With only 29% schema description coverage, the description fails to compensate. It provides no explanation for any of the 7 parameters, including the key 'q' query 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 'Full search.' is vague. It does not specify what entities are searched or how it differs from sibling tools like 'posts', 'comments', or 'communities'. It barely avoids a tautology.

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

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

No guidance on when to use this tool versus alternatives. The schema suggests it can filter by type and listing, but the description offers no context for selection.

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

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

Annotations already provide readOnlyHint=true and destructiveHint=false, but the description adds no behavioral context beyond that. It does not disclose potential side effects, auth needs, or any constraints.

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 at two words, but it under-specifies the tool's purpose. It is not sufficiently informative for an agent.

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 low complexity (one optional parameter, no output schema), the description is too sparse to be complete. It does not clarify what metadata is returned or what 'instance' means.

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

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

Schema description coverage is 0%, and the description 'Instance metadata.' does not explain the 'instance' parameter's meaning, format, or allowed values. The description fails to compensate for the lack of 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 'Instance metadata.' is vague; it does not specify the verb (e.g., get, list) or what 'instance' refers to. It provides minimal indication of purpose and fails to differentiate from sibling tools.

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

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

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

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

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

Annotations already declare readOnly and openWorld hints, and the description adds valuable context: returns a verdict (five possible values), extracted structured form, actual value with citation, and mentions it replaces multiple sequential calls. No contradictions.

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

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

Two paragraphs, front-loaded with purpose and usage examples, then scope and output details. Every sentence adds value, no fluff.

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

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

For a tool with one parameter, no output schema, and full annotations, the description covers the output format (verdict, value, citation) and scope well. Could mention error handling or rate limits 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 covers the single parameter 'claim' with 100% description coverage, providing examples and format. The tool description adds minimal extra meaning beyond this.

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

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

Clearly states the tool's purpose as fact-checking natural-language claims, specifies it handles company-financial claims via SEC EDGAR, and differentiates itself by noting it replaces 4–6 sequential calls. The verb 'validate' plus 'claim' is precise.

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

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

Explicitly says when to use with examples like 'Is it true that…?' and indicates scope (company-financial claims). However, it does not mention alternative tools for out-of-scope claims, which could be improved.

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