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

Annotations already declare this a safe idempotent read, yet the description adds substantive behavior: legacy slug forms are normalized, the 16 Meji return native text in the requested language while the 240 combined return Portuguese editorial prose, citations come with a source page, and unverified counsel/liturgical fields are withheld and surfaced in an omitted list. This is exactly the extra context annotations cannot carry.

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?

Four sentences, front-loaded with verb + resource + key, followed by scope, content-type, provenance and omission rules. Dense but every sentence adds information; the parenthetical slug examples are the only near-redundant part.

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?

With no output schema, the description carries the burden and does well: it explains what text each Odu class returns, that citations include a page, and that fields lacking a verified source appear under omitted. It stops short of describing the response's overall field structure, which is a minor gap for a 2-param lookup.

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 coverage is only 50% (slug has no description), and the description compensates by giving slug examples and documenting legacy-form normalization. The locale parameter is covered by the schema enum description, and the description reinforces it by tying language choice to which Odus return native text. Slight gap in not naming the locale default.

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?

States a specific verb ("Devolve") and resource (one of the 256 Odus) with an explicit key (slug), and the resource is inherently distinct from siblings like get_article, get_glossary and get_orixa. The description also carves out sub-scopes (16 Meji vs 240 combined), so an agent knows exactly what is retrievable.

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 use case (fetch a single Odu by slug, in a chosen locale) is implied by the slug examples and normalization note, but there is no explicit when-to-use / when-not statement and no sibling alternative (e.g. search_library or get_orixa) is named. Adequate but leaves routing to inference.

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