search_code

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

The readOnlyHint annotation already covers the read-only nature. The description adds meaning beyond that by clary specifying the result granularity ('one result per function/class') and the special behavior of 'symbols' (matches identifiers referenced in the unit). This gives useful behavioral details not present in the annotations concurrently.

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 a concise two-sentence block. The first sentence says what the tool does and states its granularity, while the second explains the non-obvious 'symbols' parameter behavior. Every sentence carries functional value and the core purpose is frontal-loaded.

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?

The tool has five parameters but only one is required and their semantics are mostly absent; the description explains only one optional parameter. The tool has an output schema, so return exploitation is not needed, but the optional `category', 'repository', and 'limit' parameters remain unclear, leaving a evaluable operational gap.

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 carries the full burden of explaining parameters. It only clarifies 'symbols'; the meaning of 'query', 'limit', 'category', and 'repository' remains undocumented. Given five parameters and zero schema descriptions, this is insufficient for an agent to use all capabilities with confidence.

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 action ('Search general source code') and specifies the resource (C/C++, Python) and a distinctive granularity ('one result per function/class'). It is also differentiates from siblings like search_docs, search_vhdl, and search_knowledge by being the general code search.

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 implies when to use this tool: for general source-code search rather than docs, VHDL, or knowledge searches. It does not explicit name alternatives or provide exclusion rules, but the resource scope and the symbol matching note give adequate context for most agent decisions.

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