Semantic Search

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false; the description adds substantive behavioral context: relevance-ranked results, cross-corpus scope, default corpus/all and k semantics, citable source fields, and a required citation instruction. No contradiction with annotations.

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 the core use case and dense with useful examples and routing guidance. It is a single long paragraph with some redundancy (citation fields appear twice), but still efficient given the tool's multi-corpus complexity.

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 multi-corpus semantic search tool, the description fully covers purpose, usage, parameters, output shape, alternatives, and citation behavior. The output schema already handles return-value details, so nothing essential is missing.

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 covers all four parameters at 100%, so baseline is 3; the description adds value by explaining q as a natural-language query with example usage, enumerating corpus options, and noting the k range and default. It omits the query alias detail, but the schema covers that well.

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?

States a specific purpose: semantic/meaning-based retrieval across named corpora (news, deals, facilities, market narratives), ranked by relevance, with concrete examples. Explicitly distinguishes itself from exact-keyword tools like get_news, list_transactions, and search_facilities, making its role unmistakable.

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?

Explicitly says to use it for conceptual/fuzzy questions where keyword filters fall short, names the exact-filter siblings it complements, and directs agents to get_market_context for full market briefings. This gives clear when-to-use and when-not-to-use guidance.

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