scf_export_document

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

Annotations already mark readOnlyHint=true, and the description reinforces this with '(read — viewer role)', adding an authorization requirement beyond the annotation. It also discloses that PDF is a binary download intentionally not offered here, which helps the agent avoid expecting a binary response.

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?

Two tight sentences with no filler. The core purpose is front-loaded, and the PDF exclusion is delivered in a clear, useful second sentence. Every clause earns its place.

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 read-only export tool with fully documented parameters and no nested objects, the description plus schema covers the essentials: role, format options, parameter sourcing, and the PDF limitation. It does not describe response shape in detail, but the description's 'text' framing makes the expected output sufficiently clear.

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 all three parameters already well documented: format's enum and default, org_id's provenance from scf_list_organizations, and document_id's provenance from scf_list_documents. The description adds minimal parameter-level meaning beyond the schema, so the baseline of 3 is appropriate.

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 clearly states the action ('Export'), the resource ('a document'), and the exact output forms ('rendered markdown or HTML text'). It also draws a bright line against PDF export, which is explicitly excluded, helping an agent distinguish this tool from any PDF-related expectation.

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 gives explicit context: use this tool for markdown/HTML text export, and if PDF is needed, fetch it from the web UI instead. It does not specifically route to sibling tools like scf_get_document or scf_preview_document, but the PDF exclusion and format scoping provide clear practical guidance.

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