Magic Envelope

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

With no annotations, the description carries the full burden and does well: it discloses the return payload (public link, per-guest link, preview image, rendered PNG per guest with a &format=jpeg toggle) and warns that the editKey is secret and required for later edit/delete. It stops short of stating auth requirements, whether publishing makes the link publicly reachable, or throughput limits.

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 tight sentences, purpose front-loaded, then output contract, then the two formatting rules an agent must apply. Dense but every clause earns its place; no padding or repetition of the schema.

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 deeply nested blocks/envelope schemas and no output schema, the description covers the output shape and key formatting rules well. It is slightly thin on auth, link permanence, and the guest-capacity implications, but nothing critical to correct invocation 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?

Schema coverage is high (90%), so the baseline is 3, but the description adds genuinely schema-absent meaning: the local date formats ("2026-11-14" whole-day vs "2026-11-14T18:00") and the {name} templating convention for per-guest addressing. This compensates for the date-block format gap the schema leaves open.

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+resource ("Create and publish an invitation or letter") that is immediately distinguishable from the create/update/get/delete sibling set. It does not explicitly name the sibling it complements (update_letter), but the action 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?

There is no explicit "use this when..." or "for modification use update_letter" guidance. The mention that the editKey should be kept "to edit or delete later" implicitly signals the follow-up workflow but leaves the when-to-use decision to inference.

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

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

With no annotations, the description carries the full behavioral burden and does well: it discloses irreversibility ("for good"), the editKey authorization requirement, and the concrete downstream destruction (links break, guest names, RSVP answers, and images erased). It stops short of stating permission scope, rate limits, or whether deletion is recoverable via any admin path.

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?

A single tight sentence that front-loads the destructive action, then the prerequisite, then the consequences. Nothing is wasted and ordering matches how an agent needs the 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 two-param destructive tool with no annotations and no output schema, the description covers the critical unknowns: permanence, the auth key, and exactly what data is lost. Only the meaning of the two parameters themselves is left thin.

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 0%, so the description must compensate, and it largely does not. "Needs its editKey" merely restates what the required array already declares and adds no meaning for what editKey is (an owner/auth token) or what id identifies. The id parameter is entirely unaddressed.

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 ("Delete a letter") with an added permanence qualifier ("for good"). The destructive verb makes it trivially distinguishable from siblings get_letter, update_letter, and create_letter without opening any schema.

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 implies when to use it (permanent removal) and states the "needs its editKey" prerequisite, but offers no explicit when-not guidance or alternative routing (e.g., "use update_letter to modify instead"). Usage context is inferable rather than stated.

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

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

No annotations are provided, so the description carries the full burden. It lists what the catalog contains but says nothing about read-only nature, side effects, authentication, or response format. The 'get' name implies a read, but that is not stated, leaving the agent to infer safety.

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 short sentences with no filler; contents are front-loaded and the usage directive follows. Efficient and appropriately sized for a simple catalog tool.

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 simplicity (no parameters, no annotations, no output schema), the description is largely complete: it lists the catalog's contents and tells when to call it. It could be improved by explicitly stating that it returns a static read-only reference, but the essentials are present.

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 tool takes zero parameters, so the schema provides no parameter info. The description adds nothing about parameters, which is appropriate for a parameterless tool. Baseline 4 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?

The description names the resource (catalog) and enumerates its contents (styles, presets, block types, etc.), making the tool's purpose clear. However, it lacks an explicit verb like 'returns' or 'lists'—the retrieval action is only implied by the tool name. Siblings are distinct (letter CRUD), so no differentiation is needed.

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 'Call this first to compose a letter,' giving clear timing and context for use. It does not mention when not to use it or name alternatives, but for a singular catalog tool no alternatives exist.

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

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

With no annotations, the description carries the full burden and does disclose the access requirement (editKey) and the exact shape of returned data, including the RSVP answer categories (yes/maybe/no) and non-responders. It does not cover failure behavior for an invalid or missing key, keeping it short of 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?

A single sentence, front-loaded with the action, with the return payload summarized compactly in a trailing clause. No wasted words.

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?

No output schema and no annotations exist, so the description usefully substitutes by enumerating the return contents. The remaining gaps are the undocumented id parameter and the absence of error/permission-failure guidance.

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 0%, so the description must compensate. It explains the purpose of editKey (proof you own the letter), but the id parameter is left entirely unexplained, so compensation is only partial.

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 (read) and resource (a letter you created), and the description of what it returns (content, links, images, RSVP answers) further pins it down. It is clearly distinguishable from create_letter, update_letter, delete_letter, and get_catalog.

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?

It gives a prerequisite ('needs its editKey') and implicitly frames the tool as owner-scoped reading, but it never says when to prefer this over siblings or what happens without a valid key. Usage is implied rather than stated.

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

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

With no annotations, the description must carry the behavioral burden, and it delivers the non-obvious traits: patch semantics (unsent fields are kept), link stability ('Links keep working'), and the critical replace-vs-append distinction between `guests` and `addGuests` with the id-then-name matching rule. It stops short of stating auth requirements (editKey) or failure/idempotency behavior, so it is strong but not complete.

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?

Four compact sentences, the core action front-loaded ('Change a letter'), then the highest-risk behaviors. Every sentence conveys a distinct, decision-relevant fact with no 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 13-parameter nested tool with no output schema, the description covers the highest-confusion areas: partial-update behavior, link persistence, and guest replace-vs-append. The block/envelope/custom/font details are left to the rich schema, which is reasonable given 77% schema coverage, though a note on required `id`/`editKey` context would round it out.

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 77%, so the schema largely documents parameters already, and the description's guest-matching and addGuests details closely echo the schema descriptions. It reinforces the patch semantics implied by the optional 'lang, style' fields but adds little syntax or constraint information beyond the schema, warranting the baseline 3.

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?

'Change a letter' gives a clear verb+resource, and the following sentences clarify it is a partial (patch) update. It does not explicitly distinguish itself from siblings like create_letter or get_letter, but the update framing against the title makes the purpose 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 implies usage by explaining patch semantics ('Only the fields you send change'), which tells the agent this is an edit-an-existing-letter tool. However there is no explicit when-to-use or when-not-to-use guidance, nor any reference to create_letter/delete_letter as alternatives.

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