Creative Specifications

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

Annotations already mark the tool as readOnlyHint=true, destructiveHint=false, idempotentHint=true, and openWorldHint=false. The description reinforces that this is a read-only, idempotent retrieval operation by stating it 'Returns' data. It adds behavioral context beyond annotations by specifying what the tool does not do (no creation/modification) and what inputs are needed. However, it does not mention error handling or edge cases (e.g., invalid format filtering), which would push it to a 5.

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 long with no filler. The first sentence immediately states the purpose and output, and the second provides input format and use case. Every phrase adds value: 'platform-specific creative requirements', 'exact image dimensions', 'Use this before building'. It is front-loaded with the most critical information.

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 (2 parameters, no output schema, 50% description coverage), the description covers the purpose, inputs, and usage guidance well. It explicitly states the return fields, which compensates for the lack of an output schema. However, it could be more complete by noting that the output is a list of specs per format, and by providing a brief note on what happens if an unsupported format is requested (e.g., returns all formats). The context signals indicate no nested objects, so the description's flat enumeration of fields is sufficient.

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 input schema has 2 parameters with 50% description coverage. The platform parameter has a description ('Platform to get specs for') but the format parameter lacks one. The description enumerates valid format values (e.g., responsive_display, video) that go beyond the schema's enum (image, video, carousel, stories), providing richer context. It also explains the effect of the optional format filter ('optional format filter'). While the schema already covers enums, the description adds clarity on how format filters output, which compensates for the missing schema description.

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 specific verbs ('Returns') and clearly identifies the resource ('platform-specific creative requirements for ad formats'). It lists the exact fields returned (image dimensions, aspect ratios, video duration/codec, character limits, CTA buttons, file size ceilings), making the tool's purpose very specific. It also distinguishes its functionality from siblings by focusing on pre-build creative validation, whereas siblings like 'competitor_benchmark' or 'budget_analyze' serve 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 explicitly states when to use this tool: 'Use this before building creatives to avoid rejection at upload time.' It provides clear input format (platform enum, optional format filter) and hints at the consequence of not using it (rejection). While it does not explicitly list when not to use it, the context signals and sibling names suggest that this tool is solely for retrieving specs, not for other tasks like analysis or creation, which is implied by its read-only nature.

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