build_analysis_prompt

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

Even with annotations carrying readOnlyHint/idempotentHint/destructiveHint, the description adds substantial behavioral context: only anchors in source_with_anchors are citable, missing required_sections blocks saving, ungrounded_sections need no anchors, and the tool forces the agent to write the draft itself. It also discloses the GR-02 error consequence with preview_save_report — meaningful behavioral detail that annotations cannot convey. No contradiction with the stated read-only, idempotent profile.

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 somewhat long but front-loaded with the core purpose before constraints, and organized into clear sections (purpose, constraints, args, returns, examples). Every sentence earns its place given the tool's complex blocking rules and sibling differentiation needs; the use/not-use examples are especially economical. Slightly heavier than ideal but well-structured for the complexity it must carry.

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?

With an output schema (BuildPromptResponse) covering the return values, the description properly focuses on usage, differentiation, and constraints. It covers when to invoke, what blocks downstream saving, how anchoring works, and the grade-C fallback path. Nothing an agent needs to call this tool correctly and avoid downstream failures is missing.

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 coverage is 100%, so the baseline is 3. The description's Args section largely duplicates schema text (path = file to analyze, start/end = block numbers, end inclusive, None = text length limit). It adds essentially no new meaning beyond the schema — the Args block is a near-verbatim restatement, so it earns the baseline without 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 opens by stating the tool collects all draft materials at once — template, anchored source text, and table of contents — establishing a clear verb-resource relationship. It further distinguishes itself from siblings by explicitly declaring 'no need to call read_document separately' and clarifying the tool only supplies format and source while the agent writes the draft. This unambiguous differentiation makes sibling confusion unlikely.

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 explicit when-to-use and when-not-to-use guidance: use it right after receiving an 'analyze this document' request; use read_document when viewing partial text; use read_document_image for grade C documents before drafting. It also specifies downstream blocking consequences (GR-02 for unlisted anchors, save blocked for missing required_sections), giving the agent concrete decision criteria for selecting this tool over alternatives.

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