quickshell_search_implementations

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

With no annotations, the description carries the full burden of behavioral disclosure. It clearly states the results are practical references, not authoritative API docs, and directs verification to other tools, setting expectations about result reliability. It does not explicitly state read-only status, but that is implied by 'search'. It also explains the source-filtering behavior and the need to call per shell. Slight gap: no mention of rate limits or response format, but the core behavioral caveat is covered.

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 front-loaded with the core purpose, then provides a long but highly useful list of example queries that clarifies the tool's scope, followed by concrete usage guidance and tool differentiation. Every sentence adds value: the example list helps agents craft appropriate queries, the source guidance prevents misuse, and the API-verification note prevents incorrect assumptions. It is dense yet structured, with no filler.

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?

Given the lack of an output schema, the description should clarify what the tool returns. It implies results are references to implementations, as it says to fetch file contents via quickshell_get_implementation. It also covers source filtering and how to compare shells. It does not explicitly state the return format (e.g., list of paths or metadata), but given the existence of a dedicated content-fetching sibling and the clear search role, the description is reasonably complete for an agent to use the 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?

The schema has 0% description coverage, so the description must compensate. It extensively documents the query parameter with many example values ('find a bar implementation', 'find a control center example', etc.), and explains the source parameter's allowed values ('caelestia' or 'noctalia') and its purpose. The limit parameter is not mentioned, but it is a standard integer with a default, so its semantics are easily inferred. Overall, the description adds strong meaning beyond the raw schema for the critical parameters.

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 clear, specific purpose: searching real-world Quickshell shell implementations (Caelestia, Noctalia) for concrete code patterns, with a long list of example query intents. It explicitly distinguishes itself from API documentation tools ('These are practical references, NOT API docs') and from quickshell_get_implementation (which retrieves file contents), so an agent can easily tell it apart from siblings.

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 explicit when-to-use instructions: restrict to one shell via the source parameter ('source=caelestia' or 'source=noctalia') and call per shell to compare approaches. It also names when to use other tools: verify API surface with quickshell_search/quickshell_get_type, and get file contents via quickshell_get_implementation. This is concrete, actionable guidance leaving nothing to inference.

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