export_report

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

With no annotations provided, the description carries the full burden—and it delivers. It explicitly discloses "Read-only; no side effects on the source," return-location differences (content vs. content_b64 vs. envelope), server-side async job behavior with automatic progress reporting, latency caveats for large models, and the signed/verifiable nature of the archive bundle. This is rich behavioral context far beyond what any structured field provides.

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 long but every sentence earns its place. It front-loads purpose and safety in the first two sentences, then uses a clean bulleted structure under each scope to organize format behaviors. Details like the archive's full inventory of contents are dense but necessary for correct invocation, and nothing is redundant with the schema.

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?

This is a genuinely complex tool—two scopes, four formats, conditional compatibility, async vs. inline returns—and the description covers every combination's behavior, constraints, return representation, and even the downstream restore workflow. The presence of an output schema means return-value details need not be enumerated, and the description appropriately focuses on the decision logic and side-effect profile.

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?

The description substantially enriches the schema: it explains how scope determines the interpretation of scope_id, maps each format enum value to its exact output representation and sync/async behavior, details the full contents of the archive envelope, and documents constraint interactions between scope and format. The only parameter not addressed is server_version, but 75% schema coverage plus this deep descriptive compensation makes the semantic space well-covered.

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 with a specific verb+resource: "Export a threat model or a tag cohort as a downloadable document." It then enumerates the exact scope/format variants, making the tool's function unambiguous and clearly distinct from siblings like import_threat_model_archive (inverse operation) and the report-type getters (get_verification_report, get_compliance_report).

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 an explicit scope/format compatibility matrix, including direct exclusions: "csv, pdf, and archive are rejected for tag scope" and "archive — Model scope only." It also names the companion tool for restore (import_threat_model_archive). However, it does not explicitly contrast against similar report/document sibling tools (e.g., get_verification_report), so it stops short of full when-not-to-use-this-instead-of-X guidance.

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