get_document

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

Annotations already declare readOnlyHint=true, so safety is covered and the bar is lower, but the description adds no behavioral context at all: no permissions or workspace scoping, no statement of whether missing documents error or return empty, and no indication of payload size. It tells the agent nothing it could not get from the annotation and schema.

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 definition is front-loaded and contains no wasted wording, so it passes on brevity, but it is terse to the point of under-specification. Conciseness here is a consequence of saying almost nothing rather than of efficient writing.

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?

There is no output schema, so the description carries the burden of explaining what comes back, and 'metadata and content' only gestures at it — no format, no statement of whether content may be truncated or omitted. For a read tool with an undocumented workspace parameter, the definition leaves gaps an agent would have to discover by trial.

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?

With two parameters and only 50% schema description coverage, the description must compensate and does not. The documentId parameter's meaning is documented in the schema ('Document _id from list_documents'), but the workspace parameter has no explanation in either place, and the description explicitly references neither parameter.

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 phrase 'Document metadata and content' identifies the resource and hints at the payload (metadata plus content), but contains no verb and does not distinguish this from sibling resources such as get_issue or get_project. An agent can infer it fetches a document, but the phrasing is a restated name plus a hint rather than a stated action.

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?

There is no guidance on when to call this versus any alternative — no mention of retrieval use cases, prerequisites, or when the document's content is or isn't included. The only indirect signal is the schema note that documentId comes from list_documents, which lives in structured data, not the description.

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