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

Annotations already declare readOnly, idempotent, closed-world and non-destructive, so the safety profile is covered. The description adds useful content about what the call reveals (filter/sort/bucket fields and designRequirements selector keys). It does not say what happens for an unknown or misspelled family, which is the main behavioral unknown for an introspection call.

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 dense sentences: the first states what comes back, the second states when to call it. No filler, no restating the title, and the payoff is front-loaded.

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 a reasonable job sketching the return contents, but it leaves the family identifier format undefined and never points at list_families for name discovery. For an introspection tool whose whole value is knowing valid names, that gap matters.

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 0% for the single required 'family' parameter, so the description carries the burden of explaining what a family is. It uses the term but never clarifies whether 'family' is a name sourced from list_families, an ID, or a path. Baseline 3 for a one-parameter tool with an unresolved identifier question.

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 the exact artifact returned: the field names a family can be filtered, sorted and bucketed on, plus the designRequirements keys its selector reads. That is a specific, verifiable scope that separates it from search_parts or part_details. The verb is implied by the title ('Describe') rather than stated, which keeps it just short of a 5.

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?

It gives an explicit trigger ('before search_parts on an unfamiliar family') and an explicit anti-pattern ('rather than guessing field names'). What it omits is the other obvious alternative: how to discover valid family names in the first place (list_families), and what to do for families already familiar.

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