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

Annotations already establish readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds meaningful behavioral context beyond that by specifying the searched fields (title, summary, incident text, tags, extracted PDF text) and reaffirming the document-only scope.

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?

Two sentences carry the full message with no filler. The purpose and corpus are front-loaded, followed directly by scope limitations and the sibling tool recommendation. Every clause 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 6 parameters, no output schema, and a read-only search context, the description covers the essential decision points: what is searched, what is excluded, and when to also call search_videos. The lack of pagination nuance is minor since schema defaults exist, leaving only small room for improvement.

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 67%, so the schema handles most parameters. The description adds value by clarifying that the free-text query searches title, summary, incident text, tags, and PDF text, but it does not explain pagination parameters (page, pageSize) or nuance around tag matching, and there are no enums to clarify.

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 opens with a precise verb and resource: 'Full-text search of the declassified UAP/UFO document archive,' and itemizes the corpus. It also differentiates from siblings by explicitly limiting coverage to documents and naming search_videos as the alternative for other media.

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?

It states when to use the tool (searching the document archive), what it covers, and what it does not cover. It goes further and gives a concrete alternative: 'run search_videos as well when researching a person, incident or topic,' making the routing decision explicit.

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