Search Transactions

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

With strong annotations (readOnlyHint=true, idempotentHint=true, destructiveHint=false) already covering the safety profile, the description adds valuable behavioral context: results are sorted by elapsed time descending and include summary statistics. It does not disclose any potential edge cases (e.g., default time windows) but the annotations reduce the burden.

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 three sentences with no filler. It front-loads the core action and resource, then adds filter options and output behavior, and ends with a clear positioning statement. Every sentence earns its place.

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 the tool's complexity (8 optional parameters, no output schema), the description conveys the essential context: what it searches, what filters are available, how results are ordered, and the primary use case. The absence of an output schema is compensated by explicitly stating the return characteristics. It is complete for a search tool with well-documented schema parameters.

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 coverage is 100%, so the baseline is 3. The description adds meaning beyond the schema by framing parameters in terms of use cases (slow transactions, error transactions, service/IP/login filters), which helps the agent understand which parameters matter for typical investigations. It stops short of detailing format constraints, but it complements the schema 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?

The description uses a specific verb ('Search') with a clear resource ('transactions (XLogs)') and details the filtering dimensions (slow, error, service/IP/login). It also mentions the result format (sorted by elapsed time descending with summary statistics), which clearly distinguishes it from more generic search tools and aligns with the stated primary use case for 'why is it slow?' investigations.

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 explicitly labels itself as the 'Primary tool for why is it slow? investigations', providing a clear when-to-use indicator. It implies a time-range search context but does not explicitly mention when to prefer sibling tools like get_transaction_detail or get_realtime_xlogs, so it lacks explicit exclusions.

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