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

With no annotations, the description carries the entire transparency burden. The only behavioral disclosure is 'Values discarded', which suggests a read-only, non-mutating operation. However, it omits any side effects, preconditions, return description, or error handling. For a tool with no annotations, this is a significant gap.

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 two short sentences with no redundancy. It front-loads the primary verb and resource ('Count keys in a JSON object') and provides a clear behavioral note ('Values discarded'). No waste, perfectly concise for a tool of this scope.

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?

The tool has 9 heterogeneous parameters, all optional, no output schema, and no annotations, yet the description fails to explain how any parameter maps to a JSON object, what the output looks like, or any constraints. A very basic tool could get away with this level of description, but the parameter chaos force the agent to guess critical usage, making it highly incomplete.

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?

Although schema description coverage is 100%, the tool description does not clarify how the input JSON object is supplied. The 'json' parameter's description ('JSON text to be validated; discarded after check') appears to describe a validation tool rather than key counting, creating confusion. The description adds no value beyond the schema and fails to compensate for the schema's lack of clarity regarding input to this tool.

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 specifies a clear action: counting keys in a JSON object, and phrases 'Values discarded' which distinguishes this from tools that return or manipulate JSON content. However, it does not differentiate itself from sibling validate-json in terms of when to use it, and it doesn't clarify which of the 9 parameters provides the JSON object.

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?

No guidance is provided on when to use this tool versus sibling tools like validate-json, domain-shape-check, or calc-eval. There are no explicitly described conditions, prerequisites, or exclusions, leaving the agent to infer use cases.

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