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

Annotations already declare readOnlyHint and idempotentHint, so the safety profile is covered. The description adds non-obvious behavioral context: 'Builder covers a configurable subset; absent settings do not establish unsupported product features,' which prevents a false negative inference. Return format is covered by the output schema.

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 output is dense but front-loaded: the core purpose leads, then filter rules, then the validate_project tie-in, then the caveat. Almost every clause carries procedural meaning. It is slightly jargon-heavy and clause-packed, keeping it from a 5.

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 an output schema present, return values need not be explained. The description covers filter combinations, the cross-tool catalogRevision usage, and a scope caveat, which is complete for a read-only enumeration tool with dependent-required constraints. It omits nothing critical for correct invocation.

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 coverage is 100% and enum/constraint descriptions are already rich, so the baseline is 3. The description adds relational semantics beyond individual fields by explaining how filters chain (omit all for components, add component then edition then target) and restates the target-requires-edition dependency.

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 states a specific verb and resource: 'Discover Builder components, targets, settings, option IDs and defaults.' It grounds the purpose in project creation and mentions validate_project for the catalogRevision handoff. It does not explicitly contrast itself with sibling catalog/discovery tools, so a 4 rather than 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?

Explicit invocation rules are given: 'Omit all filters for components; supply component for targets/settings; add edition and target for explicit option support. Target requires edition.' This tells the agent exactly which filter combinations to use, though it frames guidance around parameters rather than naming alternative sibling tools for discovery.

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