maket_image

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

With no annotations, the description carries full disclosure burden. It reveals disk storage, metadata store, combined movement, delete side effects (removes file, thumbnail, and metadata row), and the auto-optimisation/thumbnail behavior on import. It also discloses the authorization mechanism (context_token rejection). This is thorough behavioral transparency.

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 dense yet perfectly scoped: a one-sentence overview, a two-step workflow explanation, and a compact bulleted action list. Every sentence adds distinct value—no filler or repetition. The structure is scannable and front-loaded with the most critical constraint (the two-step rule).

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 tool with 12 parameters and 5 operations, the description covers all actions, the critical ordering constraint, storage model, and side effects. It mentions some return behavior (context_token, listing flags). However, without an output schema, it omits details about error conditions and full response formats, which would improve completeness for an agent deciding to invoke it.

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 100%, and every parameter already has a detailed schema description. The tool description adds a high-level action table but no parameter-level detail beyond what the schema provides. Baseline 3 is appropriate because the schema does the heavy lifting; the description does not meaningfully compensate but also doesn't need to.

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 'manage the asset library (images)'—a specific verb and resource that clearly distinguishes this tool from sibling content tools. It then enumerates the five sub-actions (list, view, meta, import, delete) with concise definitions, making the tool's scope unmistakable.

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?

Explicitly states the required two-step sequence for metadata writes: 'view → meta is a required two-step' and 'MUST be called before meta.' It also explains why (context_token proves the image was read). While it doesn't name sibling tools as alternatives, the asset-library scope and action table give unambiguous when-to-use guidance.

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