Search Topology Blocks

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint=false, so the safety profile is covered structurally. Beyond that, the description says nothing about matching semantics (substring, token, fuzzy), result ranking, result caps, or whether the search spans the whole corpus or just local blocks, which are the traits an agent would actually need.

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?

It is short and front-loaded with the key verb, with no wasted clauses. However, the brevity comes from under-specification rather than disciplined economy, so it does not fully earn the conciseness credit.

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 one undocumented parameter, no output schema, and no annotations explaining return shape, the definition should at least say what a search returns and in what order. It omits result format, ranking, and scope, leaving clear gaps for a retrieval tool surrounded by many sibling topology tools.

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% for the single required 'query' parameter, so the description carries the burden. It does add that the query is matched against titles and summaries, which is meaningful for the one parameter, but it gives no syntax, operator, or format guidance.

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 is a bare fragment, "Search titles and summaries," which largely restates the tool name (search + topology blocks) and only gestures at the searched fields. It never states what a topology block is or how this differs from sibling tools like list_topology_blocks or describe_topology_block, so an agent cannot confidently select it from the name alone.

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?

There is no guidance on when to use search versus list_topology_blocks (enumeration), describe_topology_block (single lookup), or ingest/validate_topology_contribution. No prerequisites, no conditions, no named alternatives are given.

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