layout_asset_upload

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

Beyond annotations (destructiveHint=true, idempotentHint=false), the description adds critical behavioral details: same filename creates a second asset, result is editable=false, Voog derives asset_type/content_type, and assets are served from /images not /photos. This significantly clarifies the tool's behavior without contradicting annotations.

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 front-loaded with the core purpose in the first sentence and uses paragraphs logically. It contains some minor extras (issue #140 item 4) that aren't essential but don't harm clarity. Overall it's efficient for the amount of context it provides.

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 mutation tool with no output schema, the description is reasonably complete: it explains the endpoint, serving path, asset types, editable=false, and duplicate behavior. It doesn't explicitly state the return value or error cases, but the provided context is sufficient for an agent to select and invoke this 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 coverage is 67% (site lacks description). The description adds some context about binary files and serving paths, but doesn't enhance parameter meaning beyond the schema's existing descriptions for filename and file_path (default, absolute path, allowed extensions). The site parameter remains unexplained in both description and schema, and the description doesn't fully compensate for the gap.

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: 'Upload a BINARY layout asset from disk', and clarifies scope (favicon, icon, font, inline image) with an explicit endpoint. It distinguishes itself from sibling tools by contrasting with layout_asset_create (text data only) and asset_upload (photos).

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?

Provides explicit when-to-use and when-not-to-use guidance: binaries needed a raw curl call before, photos should use asset_upload, and layout_asset_create is for text data. It also warns about duplicate filenames and recommends asset_replace for replacement, going beyond a simple use case.

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