Search Blocks

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

With no annotations, the description carries the full burden and does substantial work: it discloses AND semantics ('every word must match'), the ranking model (whole words in name, then first sentence of summary), synonym expansion ('noise' finds AWGN), and the grouped-per-family return shape. The main omission is how `limit` affects result truncation or paging, which matters for a search endpoint.

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 core purpose is front-loaded, followed by matching rules, then the grouping/output contract, then per-parameter notes. Every sentence conveys useful information, though the description is dense and slightly long; it remains reasonably structured rather than 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 search tool with an output schema already present, the description covers enough: matching semantics, ranking, grouping, and filter usage. Since return values are documented by the output schema, the only real gap is the unexplained `limit` behavior (pagination/truncation).

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 so well for three of four parameters: `query` (words matched against name/category/summary), `category` (prefix filter with example values), and `port_type` (filter with example types). `limit` is never mentioned in the description, leaving one parameter to be inferred from its name and default alone.

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?

States a specific verb and resource ('Search the block catalog by words in the block name, category or summary') and immediately describes ranking. It also names the downstream siblings (describe_block / add_block) and the exact strings they consume, so an agent can distinguish this lookup tool from the mutation/graph tools in the sibling list.

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?

Explains the intended workflow clearly: search here, then feed a concrete block_type string to describe_block or add_block. It also documents when to use the `category` prefix filter and `port_type` filter. There are no explicit exclusions or comparison against list_categories, so it stops short of a 5.

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