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

With no annotations present, the description carries the full behavioral burden and fully discharges it: the invite-only gate returns a STRUCTURED response rather than an error, the stake is held in escrow and refunded on deregister, dispute overturns slash 10%, and specific auth scopes are disclosed. This far exceeds what annotations would typically provide.

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 core purpose is front-loaded in the first sentence, and every subsequent sentence earns its place: gate behavior, parameter contracts, escrow/dispute consequences, and auth scope. It is long, but the tool involves an invite gate, strict validation, and financial stakes — there is no padding.

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?

An output schema exists, so return-value documentation is unnecessary. For a tool of this complexity, the description covers all needed ground: what it does, who is eligible, how the invite gate behaves, every parameter constraint, financial consequences (refund vs. slash), and required permissions. 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 description coverage is 0%, so the description must compensate — and it does comprehensively. It supplies the exact allowed enum values for specialisations (code, translation, data, general, content, research, infrastructure), the 1-to-7 count bound, the 422 error for invalid values, the UUID-ownership requirement for wallet_id, and the integer-and-unit semantics for stake_amount (joules). All of this exceeds what the bare schema provides.

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 opening sentence states a specific verb ('Register'), resource ('as a RAREEAI oracle'), and mechanism ('by staking joules') with the exact endpoint. It also implicitly distinguishes from the sibling set by contrasting the refundable oracle stake with the non-refundable provider listing fee, and references deregistration, which separates it from oracle_deregister.

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 gives clear application context: INVITE-ONLY at launch, the application path for non-whitelisted wallets, and the access requirement (verified account + marketplace:write). It contrasts the refundable stake with a provider listing fee, which implies the provider-registration alternative, though it never explicitly names that sibling or states a when-not-to-use condition.

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