WiFi QR code

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

Annotations only say it's a non-read-only, non-idempotent, non-destructive write; the description adds genuinely new facts: the free-tier quota (20 codes/month), that output goes to out_path or is returned inline as SVG, and that PNG requires a path. It doesn't warn about overwrite behavior or auth requirements for image generation, but coverage beyond annotations is solid.

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?

Two sentences, front-loaded with the action and its distinguishing scope, followed by output behavior and the sibling contrast. No filler; every clause carries 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?

For a 10-parameter tool with no output schema, the description covers payload, output destination, format tiering and quota, while the rich schema handles the rest. Slightly incomplete in not mentioning that PNG is Pro-only in the description text (it's in the schema) or overwrite semantics, but nothing an agent needs to call it correctly 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?

With 100% schema description coverage, the schema already documents all 10 parameters including enums, defaults and ranges. The description only restates ssid/password/auth and the out_path-vs-SVG return behavior, adding marginal value rather than syntax or format detail. Baseline 3 applies.

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?

States a specific verb and resource: 'make a QR code that joins a WiFi network when scanned', with the encoded payload spelled out (ssid, password, auth). It explicitly contrasts with the sibling qr_create ('takes plain text or a URL'), so an agent can select between the two without opening schemas.

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 WiFi-join scenario is stated clearly and the nearest alternative (qr_create for plain text/URL) is named, which gives an agent a routing rule. It stops short of explicit exclusions or pointing at the other specialized siblings (qr_vcard, qr_payment_sepa), so it's clear context rather than full when/when-not guidance.

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