audit_search

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

Annotations already communicate readOnlyHint=true and destructiveHint=false. The description adds useful behavioral context: records are 'recent' and 'redacted'. However, it does not specify what 'recent' means, how matching works, or what the result shape is.

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 a single seven-word sentence, front-loaded with the verb and resource. Every word contributes meaning and there is no repetition or filler.

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?

The core invocation is clear, and read-only annotations cover safety, but the definition leaves ambiguity around the time window for 'recent', the exact search semantics, and what redacted output contains. No output schema exists to fill these gaps.

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. 'By text' clarifies that query is the search text, but the limit parameter is not addressed at all. The schema's min/max constraints help, but the description adds only partial semantic value.

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 verb 'Search', the resource 'recent redacted audit records', and the method 'by text'. This distinguishes it from the sibling audit_recent, which likely lists recent records without text search.

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 implies text-based search over recent audit records, but it does not explicitly mention the sibling audit_recent or state when to prefer this tool over listing all recent records. No alternatives or exclusions are provided.

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