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 cover read-only, idempotent, non-destructive behavior. The description adds meaningful context beyond that by enumerating exactly what is returned—formula, entry/exit rules, direction, performance metrics, version history, trade levels. 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?

Three short sentences with the action front-loaded in the first sentence, a concise enumeration of return contents in the second, and a purpose statement in the third. No wasted words or repetition.

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

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

For a single-parameter read-only tool with full annotations and an output schema, the description is complete. It explains what the tool returns, when to use it, and where the ID comes from. Nothing critical is missing for an agent to select and 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?

Schema description coverage is 100%; the hypothesis_id parameter is well described with its source (varrd_edges, search, scan results). The description does not add parameter-specific guidance beyond referring to a specific hypothesis/strategy, so baseline 3 is appropriate.

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

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

The description clearly states a specific verb and resource: getting full detail for a specific hypothesis/strategy. It lists concrete return fields and distinguishes itself from sibling tools like search or varrd_edges by focusing on retrieval of complete details for a known ID.

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: use when you already have a hypothesis_id from varrd_edges, search, or scan results and need full strategy details to understand and act. It does not explicitly name alternatives or when-not-to-use, but the intended context is unambiguous.

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, idempotentHint=true, destructiveHint=false, and the description is fully consistent — the tool is a safe, non-destructive audit surface. Beyond that, the description adds genuinely useful behavioral context the annotations cannot: the cost model per tier ($0.50/$1/$5), the account scoping, and the statistical methodology (Bonferroni-corrected, out-of-sample, K-tracking). This adds value above the structured 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-structured with headers and front-loads the critical 'start here, FREE at depth=0' information. However, it is verbose — pricing is repeated across tiers, and closing lines like 'Machine-readable so any AI can audit the statistical rigor' and 'Full transparency' add marketing flourish rather than operational content. It could be tightened without losing meaning.

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, paid tiers, and no output schema, this description is thorough: it defines what each depth returns, how pricing works, what is scoped to the user, the filterable dimensions, and the drill-down sections. Combined with the annotations carrying the safety profile and the schema covering all parameters at 100%, nothing an agent needs to call it correctly is missing.

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 substantially enriches the 'depth' parameter by explaining exactly what each tier returns and its price, which the schema's enum alone does not convey. The remaining parameters (market, status, edge_id, section, direction, timeframe, asset_class) are adequately documented in the schema itself, so no additional compensation is needed there.

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 names the specific verb+resource: a live feed of THIS USER'S OWN statistically validated trading edges. It distinguishes itself by explicitly stating what it is NOT ('it is NOT a general/shared library'), which separates it cleanly from the sibling 'search' and AI assistant tools.

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

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

The three-tier structure gives explicit when-to-use guidance ('depth=0 (FREE — call this first)'), and the scoping exclusion ('NOT a general/shared library') rules out the wrong use case. It doesn't name a specific sibling as an alternative (e.g., directing to varrd_ai for general questions), but the 'start here' primacy plus clear tier semantics is strong practical routing guidance.

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