mac_recipe_export

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

With no annotations provided, the description carries the full transparency burden. It discloses the output format, versioning rationale, default behavior (built-ins excluded), and path/extension constraints. It does not address overwrite behavior or error handling, but it offers meaningful behavioral context beyond a bare operation description.

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 concise and well-structured: a one-sentence summary followed by three illustrative examples, then format and limitations. Every sentence serves a purpose, and the content is front-loaded with the core purpose. No redundancy or 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 3 params, no output schema, and no annotations, the description covers the essential context: what it exports, how to invoke it, the output format, and constraints. It hints at inline return via examples but does not explicitly define the return structure, which is a minor gap.

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 already has 100% coverage with highly descriptive comments for each parameter (e.g., 'omit = export all user recipes', 'Omit to return inline'). The description adds examples and format context but does not introduce new parameter semantics beyond the schema. 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?

The description opens with a specific verb and resource: 'Export user-saved recipes as a portable .mac-recipe.json bundle'. It clearly differentiates from siblings like import, search, and run by focusing on export and the bundle format. The default exclusion of built-ins is also stated, making the tool's scope 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 three concrete usage examples covering inline export, full export to file, and including built-ins. It also states limitations (path constraints). However, it does not explicitly name alternatives like mac_recipe_import for import use cases, so some guidance is implied rather than explicit.

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