find_components

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

Annotations only supply readOnlyHint, and the description's closing 'Read-only' merely repeats it. Offsetting that, it discloses genuinely non-obvious behavior: filters combine with AND, intents match any by default (a default not visible in the schema), and pagination requires carrying the same filters forward. That is meaningful behavioral context beyond the structured fields.

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?

Five dense sentences with the search purpose front-loaded and no filler; the coverage/pagination guidance is compressed effectively. Minor deduction for the ambiguous 'sorted by exact ID' clause, which adds words without adding usable meaning.

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 an 8-parameter, zero-coverage search tool with no output schema, the description covers combination logic, one default, and pagination but leaves half the filter surface unexplained and misnames the cursor parameter. An agent can call it, but not confidently for kind-, level-, or scope-based queries.

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% across 8 parameters, so the description must carry the load, and it only partially does. It clarifies intentMatch semantics ('intents match any by default'), hints at the unclassified filter, and gestures at pagination, but kind, level, scope, and limit are entirely undocumented — and worse, it refers to 'nextCursor' while the schema parameter is named 'cursor', which risks an agent passing the wrong key.

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 verb+resource (find components) is recognizable, but 'a bounded component shortlist sorted by exact ID' is oddly phrased and does not explain what a component is in this design-system context. It also never differentiates itself from siblings like get_component_catalog or get_component, so an agent must infer that this is the search/filter tool while the others are direct-fetch or catalog tools.

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 real procedural guidance: inspect coverage and broaden filters or look at unclassified records before concluding nothing is reusable, and reuse the same filters when paginating. However, it never states when to reach for find_components versus get_component or get_component_catalog, so the core selection decision is left implicit.

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