get_document

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

No annotations are provided, so the description carries the burden. It discloses that the tool returns every field including embedded time series, which is useful, and it implies the document comes from a list result. However, it does not mention authentication requirements, error behavior, or the full response structure (though an output schema exists). For a simple read operation, this is adequate but not rich.

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 two sentences, front-loaded with the primary action and scope, followed by a usage hint. Every word earns its place; there is no filler or repetition of schema details. It is concise and well-structured.

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 has only 2 required parameters, a complete enum, and an output schema, the description is fairly complete. It tells the agent when to use it (drilling into a single item from a list) and what to expect (full fields with time series). It doesn't mention error handling or authentication, but these are not critical for a simple getter and are partially covered by the output schema. It is slightly above average in completeness.

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 100%: both 'data_type' and 'document_id' have descriptions. The description adds the clarification that 'document_id' comes from a list result, but the schema already states that ('The document's 'id' field from a list result'). Thus the description adds minimal value beyond the schema, consistent with the baseline of 3 for full schema coverage.

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 uses a specific verb ('Get') with a clear resource ('one Oura document by id') and explicitly mentions that it includes every field with embedded time series. It also distinguishes itself from sibling list/getter tools by stating its role: drilling into a single sleep period, workout, or session from a list result. This fully clarifies what the tool does.

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 provides clear context: it is meant to drill into a single item after obtaining a list result from sibling tools. It does not explicitly name alternatives or state when not to use it, but the intended workflow is implicit and actionable. It gives enough guidance to select this tool over the many sibling getters.

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