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

Annotations already declare the tool as read-only, idempotent, and non-destructive. The description adds valuable behavioral context by specifying that the tool generates a self-deprecating, vulnerable, and humorous post and returns shareable text. It does not contradict annotations and gives a clear picture of the transformation performed.

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 three sentences, each earning its place. It front-loads the primary action, then explains the input and output. No unnecessary words or repetition of schema details, making it highly concise and well-structured.

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 generation tool, the description covers the core behavior and the main output ('post text ready to share'). The presence of an output schema means return values need not be detailed. The only minor gap is that it doesn't mention the customizable 'spin' option in the text, but the schema provides that information, so overall completeness is strong.

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 67%, but the existing descriptions are mostly tautological ('Your achievement') or minimal. The tool description does not explain the 'spin' parameter or its enum values, nor does it detail how to choose a spin or what 'include_lesson' truly means beyond the schema. The only meaningful guidance is the reference to 'your accomplishment,' which maps to the achievement parameter, leaving the optional parameters underspecified.

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 clearly states the tool's purpose with a specific verb ('generate'), a specific resource ('a humorous LinkedIn post from an achievement'), and the output ('post text ready to share'). It also distinguishes this tool from all siblings, which are research/monitoring tools, by emphasizing the creative, humorous transformation of an accomplishment.

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 the intended use case: input an achievement to get a humorous post. It clearly indicates what the user should provide ('your accomplishment') and what they receive. However, it does not explicitly mention any alternatives or state when not to use the tool, though no similar sibling tools exist to warrant such exclusions.

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