docs_search_docs

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

With no annotations, the description carries the full burden and does well: it discloses the two source corpora, the gh auth login prerequisite for private repos, and the automatic zh/en selection that biases results toward the query's language. It stops short of describing output shape or ranking behaviour beyond the default of 8 hits.

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?

Front-loaded with scope, then query guidance, then the follow-up workflow, then the anti-hallucination warning — a sensible order with little filler. It is dense by nature and a couple of clauses run long, but nothing is redundant.

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 no output schema, it does the essential work of implying that results carry a url to hand to get_page, and it covers auth and language defaults. The only real gap is the stale kind=github reference and no mention of what a hit record otherwise contains.

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 100%, so the schema already documents lang, limit, query and category, and the description mostly restates the language auto-detection rule. It adds useful query-formulation strategy, but also references a 'kind=github' parameter that does not exist in the schema, which muddies rather than clarifies parameter meaning.

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?

Names a specific verb and resource: full-text retrieval across roboparty.com docs plus RP1 GitHub repo README/docs, and explicitly positions the sibling docs_get_page as the follow-up step for opening a hit. An agent can distinguish it from docs_list_toc and docs_list_manuals without opening any schema.

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?

Gives explicit when-and-how guidance: pass short queries (error text, command, API name, repo name, keywords) rather than whole paragraphs, then open hits with get_page and answer quoting the source with a link. It also states a prohibition — do not answer from memory about pins, package names, versions or steps — which is exactly the kind of routing an agent needs.

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