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

Annotations only provide generic false hints, so the description carries the full burden and does so exceptionally. It discloses the exact output routing (content[0] type=image, mimeType=image/png, raw Base64), the short-lived downloadUrl in structuredContent, the SHA-256 verification value, the requirement to pass the original PNG through without editing/compositing, and the behavior of not opening widgets or repeating status messages. This goes far beyond what annotations provide.

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 long but every section earns its place with non-obvious behavioral details. It is front-loaded with the core purpose and output format, then moves to constraints and exclusions. The main downside is the lack of paragraph breaks, making it a wall of text that slightly reduces scanability. Still, no repetitive filler.

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 20 parameters, nested objects, and an output schema, the description is remarkably complete. It covers trigger conditions, input completeness, output delivery, structuredContent contents, emblem handling rules, forbidden use cases, and fallback guidance for unsupported game photos. The output schema exists, so return values do not need explanation, and nothing important appears 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 description coverage is 100%, so the schema documents all parameters well. The description still adds value by clarifying when to use homeEmblemFile vs awayEmblemFile (when user attaches emblems), how to handle transparent backgrounds and round files, and the distinction between thermal and score presets. It does not defer all param meaning to the schema, though it leaves some param-specific details to the schema's already-rich descriptions.

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 states a specific verb and resource: it creates a BoxTier-style basketball game receipt PNG. It distinguishes itself from siblings like fetch, search, and list_my_match_records by explicitly saying this is the BoxTier receipt generator and even restricts usage to basketball receipts only. The scope is unambiguous.

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 provides explicit when-to-use conditions: only when the user requests a BoxTier receipt and provides all required real values (team names, final score, date, venue, format). It also gives explicit when-not-to-use guidance: no non-basketball games, fake records, or commercial receipts; for game photos it instructs to direct the user to the boxtier.kr page. It also says to ask the user for missing values rather than guessing, which directly helps an agent choose correct behavior.

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