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

With no annotations, the description fully discloses critical behavioral traits: a quality_score below 40 triggers an automatic dispute, the fee structure (1% of trade value clamped to 50–5,000 joules, split among oracles), and the deduction timing (before provider payment). It also notes the deadline and permission requirements. This exceeds typical descriptions by explaining side effects and constraints.

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 information-dense, with each sentence providing essential details: the action, body structure, behavioral consequences, fee calculation, deadline, and permissions. It is front-loaded with the core action and follows a logical flow. While a bit verbose, the content justifies the length, and no sentence is redundant.

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 complexity of the fee structure, dispute rule, and permissions, the description covers all necessary context for an agent to invoke the tool correctly. It explains prerequisites, body fields, side effects, and timing. There is no output schema, so no requirement to describe return values; the description provides sufficient context to act.

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?

Even though schema coverage is reported as 0%, the description explicitly explains each body field: verdict with allowed values, quality_score as integer 0-100, notes max length 2000, and execution_trace as a dict for verification details. It adds meaning beyond the schema by clarifying the purpose of execution_trace and the auto-dispute threshold, making the parameters self-explanatory.

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 action (post a verdict) on a specific resource (a delivery you were assigned) and provides the endpoint. It distinguishes itself from siblings like oracle_assignments (which lists assignments) by focusing on the assessment submission action. The phrasing 'Post your verdict' is specific and 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?

The description indicates when to use the tool: when you are an assigned oracle and need to submit your assessment within the 48-hour deadline. It also lists the prerequisite permissions (assigned oracle + marketplace:write). However, it does not explicitly mention when not to use it or compare with alternative tools, but the context of being assigned is clear enough for correct usage.

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