lemon_design_principles

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It transparently states the content ('laws' + 'audit plan') and implies a read-only reference behavior, but it does not describe the return format, level of detail, or what 'audit plan' entails. This is adequate for a knowledge-retrieval tool, but not rich.

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 with zero filler. The first sentence front-loads the core content (principles list and audit plan), and the second supplies usage context and sibling differentiation. Every clause earns its place.

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 simple 2-optional-parameter tool, the description covers the resource's scope and general use. However, with no output schema, it leaves the return structure ambiguous — what does 'return the 10-step audit plan' look like? The role among siblings is clear, but the exact deliverable is underspecified.

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 baseline is 3 and the description need not compensate. The parenthetical list of principles mirrors what the schema already documents for the `topic` parameter, adding no new meaning. It does frame the values as 'permanent laws,' a slight conceptual addition, but nothing beyond schema semantics.

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 a specific resource — permanent laws of web design, listing all eight principle IDs — plus a 10-step audit plan. It distinguishes itself from siblings by stating 'everything else in the Lemon is these rules applied to 2026,' which positions it as the foundational reference tool. It lacks a strong action verb but clearly identifies what the tool provides.

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?

'Consult for any build' gives clear when-to-use guidance, and the final sentence implies sibling tools are more specific applications of these rules. However, no explicit alternatives are named, nor are there conditions for when to prefer a sibling like lemon_palette or lemon_type_spec over this tool. The guidance is implied rather than spelled out.

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