chuck_random

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

The annotations already state readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the description doesn't need to repeat that this is a safe read. It adds no context about what happens with an invalid category, what a category defaults to, or what the response contains, so it contributes little beyond the annotations.

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?

One short sentence that leads with the action. There is no filler and nothing to trim for a tool this simple.

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 trivial read-only tool with full schema coverage, no output schema, and annotations covering safety, the description says enough. The gap is the category behavior, such as a fallback default or error on unknown values, which the schema doesn't carry either.

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 schema documents the single category parameter at 100% coverage and points to chuck_categories for valid values. The description gives no meaning to category, such as defaulting to any or the behavior on unknown values, so it doesn't add to the schema.

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?

A specific verb (Get) plus resource (random Chuck Norris joke) in one sentence. It cleanly separates itself from the sibling chuck_categories, which lists categories rather than returning a joke.

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 doesn't state when to use this tool versus chuck_categories or the many other random-joke tools (joke_random, dadjoke_random, official_joke_random). It doesn't say that calling chuck_categories first lets you supply a valid category. Usage is only implied by the word 'random'.

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