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

Beyond the annotations (readOnlyHint=false, openWorldHint=true, idempotentHint=false, destructiveHint=false), the description adds crucial behavioral details: each call tests exactly ONE hypothesis, costs ~$0.25/idea, and propagates from the seed idea into related concepts. It also explains the output: 'edge or no edge, stats, trade setup.' These are not present in the schema, providing genuine transparency.

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

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

The description is well-structured with clear sections ('BEST FOR', 'Returns', alternative tool). It is slightly verbose with marketing phrases like 'comprehensive market structure knowledge graphs ever built', but every sentence carries information. Front-loaded with the core purpose, and examples aid comprehension. A minor trim could improve conciseness, but it is not wasteful.

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 (6 parameters, output schema exists, annotations present), the description provides sufficient context for an AI agent to decide when to invoke it. It covers what the tool does, example usage, cost, output summary, and the distinction from a sibling tool. The output schema handles return values, so no further elaboration is needed. This is a complete description.

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 baseline is 3. The description adds illustrative meaning to the 'topic' parameter via the 'momentum on grains' example, but does not enhance understanding of other parameters like 'context', 'markets', 'test_type', or 'search_mode'. It does not contradict or significantly add beyond the schema descriptions, so a 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: 'Point VARRD's autonomous AI in a direction and let it discover edges for you.' It explains that it generates and tests hypotheses, and explicitly distinguishes this from the sibling tool 'varrd_ai' for controlled testing. The verb 'discover' and resource 'edges' make the primary function 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?

It explicitly says 'BEST FOR: Exploring a space broadly' and provides concrete examples of when to use it. It also gives a clear exclusion criterion: 'Use 'varrd_ai' instead when YOU have a specific idea to test and want full control over each step.' This is textbook usage 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 is free (no credits consumed), returns a Stripe Checkout link for card, and provides a deposit address and payment_intent_id for crypto. It also explains the two-step confirmation behavior, offering context 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 well-organized with clear headings and numbered steps, making it scannable. Every sentence provides actionable information without waste.

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 the full payment lifecycle, including fallback to check_balance, exact call sequence for crypto, and the condition of instant credit addition after confirmation. Given the complexity of a payment tool, this is complete.

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

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

The schema already describes all three parameters, but the description adds operational meaning by explaining the two-phase crypto flow (first with payment_method='crypto', then with payment_intent_id to confirm) and the default amount_cents. This makes the parameters' roles clear in context.

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

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

The description clearly states the tool 'Buys credits for the edge library and AI research' and details the two payment methods. It also distinguishes itself from the sibling check_balance by referencing it for post-payment confirmation.

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: card for user-mediated Stripe payment, crypto for autonomous machine-to-machine flow when wallet access is available. It also instructs the agent to call check_balance after card payment, naming a sibling alternative.

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

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

Beyond annotations (readOnlyHint, idempotentHint, destructiveHint), the description adds valuable context: 'Free — no credits consumed' and the auto-detection behavior with 'recovered_cents' in the response. This enriches the agent's understanding of side effects and return values.

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

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

Three focused sentences, each earning its place: first states the core purpose, second addresses cost, third provides a critical usage scenario and expected response. No redundancy or filler.

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

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

The description fully covers the tool's purpose, usage context, and important behavioral nuances. With output schema available and annotations present, no additional explanation is needed for a zero-parameter tool.

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

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

The tool has zero parameters and the schema is empty, so there's nothing to explain. Baseline for 0 params is 4, and the description appropriately mentions the response field 'recovered_cents' which aligns with the output schema.

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

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

The description uses specific verbs ('Check', 'see', 'auto-detects') and clearly identifies the resource ('credit balance', 'credit packs', 'completed payments'). It distinguishes from siblings like buy_credits by focusing on checking and payment confirmation, not purchasing.

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 the tool is free and safe to use, and gives a concrete scenario ('call this after your user pays via a checkout link to confirm credits were added'). This provides clear when-to-use guidance and implies alternatives like buy_credits for purchasing.

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

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

The description goes beyond the annotations by disclosing important behavioral traits: it 'Costs credits', requires a specific prerequisite ('at least 5 strong edges'), and explains the process ('Profiles your strategies, searches today's news...'). It also describes the output format with '↳ lines'. These details are not present in the annotations and add significant transparency.

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

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

The description is concise and well-structured: the first sentence gives the main purpose, the second explains the output detail, and the third states prerequisites and cost. Every sentence adds value, and there is no wasted text.

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 tool has no parameters and an output schema exists, the description is complete. It covers the core behavior, prerequisites, cost, and what the user can expect in the output. No gaps are apparent.

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 tool has zero parameters, so the baseline for parameter semantics is 4. The description adds no param-specific information because there are no params, which is acceptable; schema coverage is 100% by default.

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

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

The description clearly states the tool's function: 'Get a personalized market news briefing based on your validated edge library.' The verb 'get' plus the resource 'briefing' is specific and distinguishes it from sibling tools like general 'search' or 'varrd_ai'. It also explains the unique value proposition of tying headlines to the user's positions and 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 provides clear context for when to use the tool: it requires 'at least 5 strong edges in your library' and is intended for a personalized briefing. However, it does not explicitly mention alternatives or when not to use it, so it falls just short of the 'explicit when/when-not' benchmark.

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 aligns with annotations (readOnlyHint, idempotentHint) and adds behavioral detail about returned data (performance metrics, version history, trade levels), fully disclosing what the tool does beyond safety properties.

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

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

The description is two sentences with clear front-loading. The second sentence is somewhat general ('Everything an agent needs...') but not overly verbose. Minor improvement possible.

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 parameter count, full schema coverage, presence of output schema, and comprehensive annotations, the description fully covers what the agent needs to know about this simple retrieval tool.

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

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

Schema coverage is 100%, and the description adds the context that hypothesis_id comes from 'search or scan results,' which is helpful for correct invocation. However, no additional parameter-specific details are given.

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

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

The description explicitly states 'Get full detail for a specific hypothesis/strategy' and enumerates specific content (formula, entry/exit rules, performance metrics, etc.), making the purpose very clear and distinguishing it from siblings like 'search'.

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

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

The description implies the tool is used after discovery via search/scan ('from search or scan results'), providing clear usage context. However, it does not explicitly state when not to use it or mention alternatives beyond the sibling list.

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 mark the tool as destructive and idempotent. The description adds valuable behavioral context beyond these hints: it notes the operation is free ('Free — no credits consumed') and that the old session is effectively discarded, letting the agent plan accordingly.

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

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

The description is three sentences long, front-loaded with the purpose, and each sentence earns its place: what it does, when to use it, cost, and next step. No filler or redundancy.

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

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

Given the tool's simplicity (one required parameter), existing annotations, and an output schema, the description is complete. It covers when to use, cost implications, and the aftermath, leaving no critical gaps.

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

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

Schema coverage is 100%, so the parameter description already explains session_id. The description adds context by specifying this is a 'research session' and explains that the next call should omit session_id, giving the parameter semantic meaning beyond the schema's generic wording.

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

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

The description opens with 'Kill a broken research session and start fresh' — a specific verb and resource that clearly states what the tool does. It distinguishes reset_session from sibling tools like search or buy_credits by focusing on session lifecycle management.

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

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

It explicitly states when to use the tool ('when a session gets stuck, produces errors, or enters a bad state') and provides a clear next step ('call research without a session_id'). The guidance is practical and unambiguous, covering the primary use case and follow-up action.

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 safety profile is known. The description adds meaningful behavioral context: it searches only saved hypotheses (scope) and returns ranked results with key stats (win rate, Sharpe, edge status), which is not in annotations. It does not mention pagination or rate limits, but it adds enough beyond annotations to warrant a 4.

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

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

The description is two sentences, front-loaded with the core action, and every sentence earns its place. It states what the tool does, what it returns, and when to use it without any redundant filler.

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

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

With strong annotations, a fully described schema, and an output schema present, the description delivers the essential purpose, usage, and return behavior. For a simple search tool with one required parameter, this is complete and leaves no obvious gaps.

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

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

Schema description coverage is 100%, with each parameter (query, limit, market) already well-described. The description reinforces the query parameter's purpose ('keyword or natural language query') but does not add new syntactic details or clarify parameter behavior beyond the schema, so it sits at the baseline of 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's function: 'Search your saved hypotheses by keyword or natural language query.' It specifies the resource (saved hypotheses), the action (search), and the method (keyword or natural language). It also mentions the output ('returns matching strategies ranked by relevance'), which distinguishes it from siblings like get_hypothesis.

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

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

The description provides explicit usage context: 'Use this to find strategies you've already validated.' This tells the agent when to invoke this tool (for searching existing validated strategies) but does not explicitly name alternatives or exclusion cases, so it falls short of the highest bar.

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

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

Beyond annotations (readOnlyHint=false, openWorldHint=true), the description discloses cost (~$0.25/turn), the multi-turn session state, the 'ONE hypothesis at a time' constraint, edge verdict categories, and terminal states. This is rich behavioral context not captured in 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?

Though lengthy, the description is sectioned logically (MULTI-TURN, HYPOTHESIS INTEGRITY, KEY CAPABILITIES, EDGE VERDICTS, TERMINAL STATES) and every sentence carries functional guidance for a complex tool. It is front-loaded with the core purpose and then details the workflow without 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 complex multi-turn tool, the description covers the full lifecycle: session creation, hypothesis testing, allowed/not-allowed patterns, verdict interpretation, and stopping criteria. It references context fields (has_edge, next_actions, edge_verdict) and assumes an output schema, so the agent is fully equipped to use the tool correctly.

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

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

Schema coverage is 100%, but the description adds value by giving concrete message examples ('test it', 'show me the trade setup') and clarifying session_id behavior (omit to start new). This supports the schema without redundancy, though it doesn't define parameter constraints beyond what's already present.

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

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

The description opens with a clear statement: "Talk to VARRD AI... Describe any trading idea in plain language and the system handles everything..." It enumerates specific capabilities (charting, statistical tests, backtesting, trade setups) and distinguishes from siblings by emphasizing interactive multi-turn research rather than autonomous execution.

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 an explicit multi-turn protocol, including 'First call creates a session. Keep calling with the same session_id, following context.next_actions each time.' It also gives allowed/not-allowed examples for hypothesis testing, but doesn't explicitly reference sibling tools as alternatives, so it lacks explicit when-not/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 mark readOnlyHint, idempotentHint, and destructiveHint, and the description agrees fully. It adds substantial behavioral context: free at depth 0, always safe to call, pricing tiers, account scoping, validation methodology, and drill-down behavior after purchase. No contradiction with annotations.

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

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

The description is front-loaded with the most important instruction ('start here') and organized clearly into tiers and validation notes. It is longer than minimal, with some redundant marketing phrases like 'Full transparency' and repeated validation claims, but the structure makes the content scannable and decision-relevant.

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 8 optional parameters, no output schema, and multi-tier pricing, the description is remarkably complete: it covers scoping, pricing, return contents per depth, filter semantics, no-edge behavior, and output sections. An agent has enough context to call the tool correctly and set user expectations.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds real value by explaining the business semantics of depth tiers, what each tier unlocks, and the drill-down sections, which helps an agent choose parameters. It does not deeply elaborate on market, status, or timeframe syntax, but the schema already covers those.

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 opens with a specific verb+resource: it is a live feed of the user's own statistically validated trading edges, scoped to the connected account. It clearly distinguishes itself from a general/shared library and tells the agent this is the primary starting point.

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?

Strong when-to-use guidance is present: 'THE PRIMARY TOOL — start here' and 'call this first', plus a clear exclusion that if the user has no edges it returns none and is not a general library. However, it does not explicitly name sibling tools as alternatives or explain when to prefer varrd_ai, search, or get_hypothesis.

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