create_signed_upload

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

Beyond the annotations (readOnlyHint=false, openWorldHint=true, idempotentHint=false), the description discloses the real behavioral contract: PUT raw bytes to upload_url with the returned headers, 15-minute slot expiry, 403 on Content-Type mismatch under pinning, per-file in-place failure reporting, HEIC rejection, and the 50MB ceiling. These are exactly the operational facts an agent cannot derive from structured fields.

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?

Purpose, limits and formats are front-loaded, and the dense paragraph is almost entirely load-bearing operational detail. Minor waste exists — the pin_content_type 403 behavior appears both in the description and in the schema parameter text — and the block would scan better as short sentences or lines.

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 6-parameter tool with no output schema, the description supplies the full round trip: accepted formats, size cap, slot semantics, the PUT step with headers, expiry window, and how the resulting public_url feeds create_post for both regular media and LinkedIn documents. Nothing essential to a correct first invocation 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 baseline is 3; the description still adds meaning by framing filename/content_type/size and files as mutually exclusive modes ("omit when using files" / "use instead of") and by explaining that the files array yields one slot per entry with failures reported in place. It restates the pin_content_type 403 rule already in the schema, which caps it below 5.

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 ("Create signed upload URLs") and immediately scopes it by asset class ("larger images, videos or PDFs") and batch size. It also names the downstream consumers (create_post / create_posts_batch), so an agent can place the tool in the workflow without opening the 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?

It clearly states the two calling modes (single-file fields vs. files array) and the post-call next step, including the PDF-specific path (post_type document). It does not explicitly compare against sibling media tools like upload_media or create_media_drop, so the agent must infer why this exists beyond "larger" files — that keeps it short of a 5.

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