varrd_edges

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.