get_lever_state

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

With no annotations provided, the description must fully disclose behavior, and it does extensively. It explicitly states 'read-only', explains null/default states (null until first tick, {} until measured), and details how flags like needsReplenishment behave. This provides the agent with a clear understanding of side-effects and state semantics.

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 an extremely long single sentence with numerous nested parentheticals, making it difficult to parse. Although it is information-dense, it lacks structural breaks (e.g., bullet points, sentences) and buries key facts. This reduces readability and violates the principle of front-loading with concise scannable 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 the tool's complexity (many state fields, relationships to other operations), the description is exceptionally complete, covering all reported state elements and their meanings. It even explains how the discovery block connects to /build-list, add_prospects, and /evaluate. Since no output schema exists, the description carries the full burden of describing return content, which it does thoroughly.

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% parameter coverage with descriptions for both projectId and batchSize. The description does not add significant parameter-specific meaning beyond the schema; it mentions batchSize in context of batchPlan but the schema already describes it. Therefore 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 opens with 'Read-only snapshot of the project's outbound optimizer', clearly identifying the tool's purpose and immediate read-only nature. It enumerates the specific state components (draw weights, channel affinity, targetingLifts, discovery block, etc.), distinguishing it from sibling tools like run_lever_tick (which executes a tick) and get_lever_decisions (which retrieves decision records).

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 clearly implies the tool is for inspecting the current state of the optimizer, contrasting indirectly with actions like running a tick or registering strategies. However, it does not explicitly state 'use this when you need to view the optimizer state' or exclude specific alternatives, so it falls short of full explicit guidance.

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