get_component

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

The description discloses several behavioral traits beyond the readOnlyHint annotation: it explains the resolution behavior (exactly one component vs. error listing available names), the ambiguity response structure ({ ambiguous, matches, instruction }), and the nature of the data ('static source-site facts, never runtime frequency'). It also clarifies that detail is opt-in and what each detail option returns. The only minor gap is not explicitly stating pagination behavior for limit/offset, but the schema covers those parameters.

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 dense but well-structured. It front-loads the core purpose and read-only nature, then explains resolution behavior, detail options, ambiguity handling, and usage guidance. Every sentence adds value, though it is somewhat long. The structure is logical: purpose → behavior → parameters → usage → alternative. It earns a 4 for being comprehensive without being bloated.

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 tool with 5 parameters, no output schema, and no schema descriptions, the description covers all essential aspects: what it does, how to use it, what the return values look like (component JSON, error, ambiguity object), what each detail option returns, and when to use an alternative. The ambiguity resolution instruction is particularly valuable for an agent. Nothing critical is missing for an agent to invoke this tool correctly.

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%, so the description must compensate. It does: it explains the 'context' parameter ('Pass context (your current working file or directory) so same-name components resolve by path scope'), the 'detail' parameter (lists all enum values and their meanings), and the 'name' parameter (lookup by name or id). It doesn't explicitly explain 'limit' and 'offset', but those are standard pagination parameters with clear schema constraints. The description adds significant meaning beyond the raw schema.

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: 'Look up a component by name or id' and distinguishes it from siblings by noting 'For a list of all components, use get_design_context with category 'components' instead.' It also specifies the resource (component) and the action (look up), making it easy for an agent to understand what this tool does.

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 provides explicit guidance on when to use this tool ('Use this when you need implementation details for a known component to reuse it rather than recreate it') and when not to use it ('For a list of all components, use get_design_context with category 'components' instead'). It also explains the ambiguity resolution process, which is a clear usage guideline for handling multiple matches.

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