VARRD — Statistically Validated Trading Edges + AI Research Engine

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?

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds valuable context about the return payload (formula, entry/exit rules, performance metrics, version history, trade levels), which goes beyond the annotations. No contradictions.

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

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

Two sentences, front-loaded with the verb and resource, then a compact enumeration of return contents. Every sentence adds value with no 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?

For a simple read-only fetch with a single param and an output schema, the description is sufficiently complete. It tells the agent what it will get back and the scope of the tool. No major gaps given annotations and schema.

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

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

Schema coverage is 100% with a single parameter 'hypothesis_id' described as 'from search or scan results'. The tool description does not add additional parameter semantics beyond restating that it targets a specific hypothesis/strategy, so the schema carries the burden.

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 'Get' with a specific resource 'hypothesis/strategy', and clarifies it returns 'full detail' including formula, rules, performance metrics. This clearly distinguishes it from siblings like search or varrd_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 implies usage when an agent needs complete strategy details, but does not explicitly state when to use it instead of alternatives such as search or varrd_edges. The schema hint 'from search or scan results' provides some context but the description itself lacks explicit 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?

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 declare readOnlyHint=true, but the description adds substantial context: cost tiers, what is free versus paid, the fact that depth=2 includes drill-down sections free after purchase, and the statistical methodology (Bonferroni-corrected, out-of-sample validated). It also notes 'always safe to call,' aligning with the read-only nature without contradicting it.

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

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

The description is long but well-structured with a clear hierarchy: primary call-to-action, three tiers, and methodology footer. Every sentence adds useful information about costs, contents, or credibility. It is not unnecessarily verbose; the length matches the complexity of the tool.

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

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

With no output schema, the description must explain return values, and it does: depth=0 returns markets and status, depth=1 lists direction/stats/levels, depth=2 includes methodology and performance analytics. It also covers drill-down sections and pricing. This is complete for an 8-parameter tool with three modes.

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 value by explaining the depth tier semantics in terms of cost and content, and by clarifying how 'section' interacts with depth=2. This goes beyond the schema's brief enum descriptions, helping the agent understand the trade-off between depths.

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 'THE PRIMARY TOOL — start here' and clearly states it provides a 'Live feed of statistically validated trading edges' with actions like 'See what's firing right now, get trade levels, or audit the full methodology.' This uses a specific verb + resource and distinguishes it from sibling tools by positioning it as the primary edge library.

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 'start here' and 'always safe to call,' giving clear context for when to use this tool. It does not explicitly mention alternatives or exclusions, but the 'start here' instruction serves as primary guidance. The three-tier structure also explains which depth to choose based on need.

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