scf_get_document

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

Annotations already flag readOnlyHint=true, and the description reinforces this with 'read' and adds extra behavioral context: the required viewer role, full-document scope, and the merge-state values returned (clean, edited, conflicted, pending retirement). This goes beyond the annotation without contradicting it.

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?

One compact, front-loaded sentence states purpose, required role, return scope, and merge-state vocabulary with no wasted words.

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?

For a simple two-parameter read with readOnlyHint and fully documented parameters, the description adequately conveys what the caller receives. It could be slightly more complete by pointing to the section-level sibling or mentioning access failure behavior, but nothing essential is missing for correct invocation.

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%, with both org_id and document_id documented and linked to scf_list_organizations and scf_list_documents. The description itself adds no parameter-level semantics, so it meets the baseline of 3 rather than exceeding it.

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 names a specific operation ('Get one generated document in full'), the resource (a single generated document), and the scope (metadata plus every section with merge state). This differentiates it from list-style siblings like scf_list_documents and section-level tools like scf_get_document_section_generated, and closes with an explicit invocation cue: 'Use this to read a document.'

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?

It clearly establishes when to use the tool: when an agent needs to read a full generated document as a viewer. However, it does not explicitly name sibling alternatives or state when not to use it, such as pointing to scf_get_document_section_generated for a single section or scf_get_document_history for history.

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