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

With no annotations provided, the description carries the full burden of behavioral disclosure. It discloses important behaviors: the output is a download link expiring in ~48 hours, markups appear in Bluebeam Revu's Markups List, the user controls placement while the tool ensures format, and nothing submitted is stored. It does not detail edge cases like what happens on invalid PDFs, but the disclosed behaviors are useful and non-obvious.

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 two sentences but packs in essential info: annotation types, input format, PDF input methods, return format, expiration, Bluebeam compatibility, placement control, and privacy. Every phrase carries meaning; no filler or redundancy.

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?

Given the tool's complexity (nested markups array, coordinate spaces, multiple parameter options, no output schema), the description covers the key inputs, the return link, expiration, and privacy. It does not explain coordinate-space semantics, but the schema provides that detail, so the description is complete enough for an agent to use the tool correctly.

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 high (86%), so the schema already documents most parameters. The description adds the concept of a 'markups JSON' and 'placement coordinates', but it does not go beyond the schema for individual parameters. This meets the baseline 3 for high schema coverage.

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 uses a specific verb ('Add') with a clear resource ('real Bluebeam-compatible annotation objects to a drawing PDF') and enumerates example annotation types (counts, length/area measurements, RFI clouds, callouts). This clearly distinguishes it from the sibling steel calculation/reference tools, which have entirely different purposes.

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 clearly explains the input format ('markups JSON you supply plus placement coordinates'), how to pass the PDF (https URL or base64), and even gives a preference hint ('prefer pdf_url for drawing sets'). It does not explicitly state when to use this vs. alternatives, but the sibling tools are so different that the context is clear.

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