Get Document Plaintext

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

Annotations already establish readOnly/idempotent/non-destructive safety. The description adds genuinely useful behavioral context beyond them: the per-call fetch caps (100 pages, 100000 chars) and the fact that a nextStartPage continuance marker is returned when more remains. It could still say more about transient errors or truncation semantics, but this is solid added value.

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 sentences, zero filler, with the primary purpose front-loaded ahead of the pagination caveat. 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 read tool with no output schema, the description adequately covers the return shape (page separators, continuation marker) and the safety profile is handled by annotations. It is largely complete, with only minor gaps around exact return structure.

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%, so baseline is 3, but the description goes further by clarifying the operational meaning of the budget-related parameters (100000 default chars, 100-page cap) and introducing the nextStartPage continuance mechanism that maps to the startPage parameter. It meaningfully contextualizes how the parameters behave.

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 ('Get') and resource ('transcribed text of a whole document') and scopes it clearly as whole-document and single-call. An agent can distinguish this from the sibling page-level tools (transkribus_page_get_plaintext, transkribus_page_get_text) without opening a schema.

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 phrase 'a whole document in one call' implicitly signals when to use this over per-page retrieval, but the description never names alternatives such as transkribus_doc_get_fulldoc or transkribus_page_get_plaintext, nor states exclusions. Usage is implied rather than explicit.

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