search_kcl_samples

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

No annotations are provided, so the description carries the full burden. It discloses that multipleFiles is a 'best-effort hint only' and advises calling get_kcl_sample for a reliable answer, which is useful. However, it doesn't disclose pagination, rate limits, or error cases beyond returning an error string, leaving some transparency gaps for a search operation.

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 well-structured with a one-line summary followed by args, returns, and caveats clearly labeled. It's thorough without being bloated; the docstring format is readable and front-loads the core purpose.

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 there's an output schema, the description needn't fully explain return values, but it does anyway, which is helpful. It documents the return list fields and the error fallback, and provides the multipleFiles caveat with a pointer to a reliable alternative. For a search tool with 2 params and no annotations, this is reasonably complete.

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, and it does. It explains query is 'case-insensitive' and max_results is 'Maximum number of results to return (default: 5)', adding semantics beyond the bare schema. It also documents the return structure in detail.

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?

Description clearly states it searches KCL samples by keyword across titles and descriptions, and returns results ranked by relevance. The purpose is specific and clear, though sibling tools like search_kcl_docs and search_org_dataset_semantic share similar search patterns, so explicit differentiation is limited.

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 explains the tool searches all KCL sample titles and descriptions, giving implied usage context. However, it doesn't explicitly contrast with search_kcl_docs, search_org_dataset_semantic, or list_kcl_samples, and there's no statement of when NOT to use this tool.

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