mantle_get_opportunity

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

With no annotations provided, the description carries the full burden of conveying safety and behavioral traits. It does state 'Calls GET /api/opportunities/:id', which indicates a read-only operation, but it does not explicitly confirm non-mutating behavior, error handling, or any permissions required. This is minimal but not absent, scoring a 3.

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?

Single sentence, direct, starts with the verb and object. No filler or repetition. Ideal conciseness for a simple getter.

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?

This is a simple tool with one parameter and no output schema; the description explains what it returns (full details) and how to invoke it (by ID via the endpoint). It is adequate for the agent to select and call, though it could mention returned payload structure or errors, but for this complexity level, it's complete enough.

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 single parameter 'id' is already well described in the schema as 'Opportunity ID (UUID)' with 100% coverage. The description merely says 'by its ID', adding no further constraint or format detail. Baseline for high schema coverage is 3, and no incremental value is provided.

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?

Clear 'Get' verb targeting a specific resource ('full details for a single yield opportunity'), with the endpoint explicitly stated. This clearly differentiates from siblings like mantle_list_opportunities (list vs single) and mantle_get_opportunity_chart (chart vs full details).

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 implies the use case: when you need full details for one known opportunity by ID. However, it does not explicitly mention when not to use it or contrast with alternatives, so it lacks the explicit exclusions needed for a 5.

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