ym_search_methods

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

Annotations already indicate readOnlyHint=true and openWorldHint=false, so the read-only nature is covered. The description adds useful behavioral details: it returns a JSON list, orders results 'best first', and supports both Russian and English. These go beyond the annotations and help the agent anticipate output. It does not mention pagination or auth, but those are less critical 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 description is two short sections: a one-sentence purpose statement followed by a compact parameter breakdown. Every sentence adds value, no filler, and important info (return format, constraints) is front-loaded. It is efficiently structured for quick parsing.

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 it has a simple parameter set and an output schema exists, the description covers the necessary invocation details: parameters are explained, return format is stated, and read-only behavior is conveyed via annotations. The only missing contextual aid is usage guidance, but that is already scored under dimension 2. Overall, it is complete enough for an agent to call 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 input schema provides no descriptions for the parameters (coverage 0%), so the description carries the full burden. It explicitly defines 'query' as free text with examples, and 'limit' with a range (1-50). This fully compensates for the schema gap, giving the agent everything needed to set the parameters correctly.

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 clearly states the tool's function: 'Search the endpoint catalog by keyword' and adds a specific capability (works in Russian and English) that distinguishes it from other search tools. The verb 'Search' and the object 'endpoint catalog' are specific, and it is clearly different from siblings like ym_describe_method or ym_map.

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 this tool versus alternatives. It does not mention what scenarios call for this search method vs. ym_map for browsing structure or ym_describe_method for details. The description only explains what it does, not when it is the right choice.

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