get_principle

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

Annotations only declare readOnlyHint=true, so the description carries most of the burden, and it discloses a genuinely non-obvious behavior: with UXUI_API_KEY set (pro mode) the full guide body is returned in `content`. That conditional, credential-dependent response shape is exactly the kind of thing an agent needs and cannot infer from the schema. It does not cover failure behavior for unknown slugs.

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 lookup key, then the return payload, then the use case. The enumeration of return fields is dense but earns its space because there is no output 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?

With no output schema, the description does the heavy lifting by naming the returned fields and the pro-mode variation, and the schema covers the two parameters. The remaining gap is edge-case behavior — unknown slug, locale fallback — which an agent calling this tool would reasonably want.

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 100%, with both `slug` and the `locale` enum documented in the schema itself. The description reinforces the slug-as-lookup-key idea and ties `content` to the API key, but adds no format or validation detail beyond the schema, so the 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 ('Get a UX/UI principle by its slug') and enumerates exactly what comes back: metadata, summary, citations, and a guide link. The 'by its slug' lookup key implicitly separates it from search_principles and list_principles, which take query/filter inputs rather than a single identifier.

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?

'Use this to identify, summarize or cite a specific principle' gives a clear usage context tied to the known-slug case. It stops short of explicitly naming alternatives (e.g., 'if you only have a topic, use search_principles'), so there is no stated when-not-to-use.

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