UAPDrop Research Archive

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

Annotations already cover the safety profile with readOnlyHint=true and destructiveHint=false. The description adds useful context about the cited-references ledger and citation backing, but it does not address errors, auth, pagination, or exact return format.

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 two sentences with no filler, front-loading the action and resource while immediately stating the ledger feature that differentiates the tool. 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?

For a simple one-parameter read tool, the description conveys the main returned content (profile plus cited references) and relies on annotations for safety. However, it omits slug semantics, error behavior, and any mention of how the cited ledger is structured, so it is not fully self-sufficient.

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?

The schema has one required slug parameter with 0% description coverage, and the description does not explain what slug means, where to obtain it, or what format it should take. It only weakly implies that the slug selects which entity profile to fetch.

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 names a specific verb and resource ('Fetch one entity profile') and highlights the distinguishing feature ('full cited references ledger'). The word 'one' clearly separates it from list-style siblings such as list_beings.

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 this tool is for fetching a single entity profile, but it never explicitly states when to use it over alternatives like list_beings or get_document. Usage context is inferable from the wording but not directly guided.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context about the return scope: it returns the document in full, including the attachment gallery, which is not implied by the schema alone.

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 short sentences with no redundancy. The primary action and scope are front-loaded, and the identifier requirement is stated compactly in the second sentence. Every word 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?

For a simple fetch tool, the description is largely complete: it explains what is fetched and how to identify the document. The lack of an output schema and the fact that no parameters are marked required make the explicit 'either/or' instruction valuable. Minor gaps, such as behavior when both id and external identifiers are supplied, keep it from a 5.

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 important relational semantics by specifying the alternative identifier patterns: either `id` alone, or both `releaseProgram` and `externalId`. This goes beyond the individual property descriptions and clarifies a constraint not represented in the schema's required fields.

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 ('Fetch') and a specific resource ('one archive document in full'), and adds the distinguishing detail that it includes the attachment gallery. This clearly separates it from sibling tools like search_documents or related_documents.

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 provides clear operational context: use this tool when you need a single full document, and it states the valid identifier combinations. It does not explicitly name alternatives or exclusions, but the 'one archive document in full' framing makes the intended scope clear.

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

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

Annotations already establish that this is a safe read operation (readOnlyHint=true, destructiveHint=false). The description adds useful output-scope context by saying the article is returned 'in full' and includes related-commentary links, but it does not disclose additional behaviors such as error cases, response shape, or pagination.

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, tightly written sentence that conveys the core action and a distinguishing detail. There is no redundancy or filler, and the most important information is front-loaded.

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 simple get-by-ID operation with one parameter and no output schema, the description is largely sufficient. It communicates the main return scope ('in full') and the notable related-commentary links. A minor gap is that it does not clarify what fields 'full' entails or how missing/invalid IDs are handled, but the operation is straightforward.

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 for the undocumented newsId parameter. The phrase 'Fetch one news article' makes it clear that newsId identifies which article to fetch, but the description does not explain the expected format, provenance, or how the ID relates to other tools. This is adequate for a single self-descriptive parameter but not thorough.

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 and resource: 'Fetch one news article in full,' which clearly identifies the operation and target. It also notes the inclusion of related-commentary links, helping distinguish this tool from list_news and related_commentary siblings.

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 usage: use this when you need a single full news article by its ID. However, it does not explicitly compare with sibling tools like list_news, related_commentary, or get_document, nor state when one alternative should be preferred over another.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds that the result includes the full media set and that the lookup is by two identifiers, which is useful behavioral context beyond the annotations. It does not address not-found behavior, but that is minor for a simple read-only getter.

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?

One clean, front-loaded sentence states the resource, payload, and lookup key without wasted words. Every phrase contributes meaning.

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 two-parameter read-only getter, this description is nearly complete: it names the compound key and promises the full media set. There is no output schema, so slightly more detail on empty or missing results would round it out, but an agent can invoke it confidently in most cases.

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 0%, so the description must carry parameter meaning. It tells the agent that source and external id together form the key, which is helpful, but it does not define valid sourceKey values or externalId format. The parameter names still do most of the work.

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 ('fetch'), a precise resource ('one sighting record'), and distinguishes itself with 'full media set' and the compound lookup key ('source and external id'). This clearly separates it from siblings like search_sightings or get_news.

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 condition for use is implied clearly: call this when you have the source and external id and need a single sighting with its media. It does not explicitly name alternatives or exclusions, but the compound key makes the appropriate context obvious.

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

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

Annotations already mark the tool as read-only and non-destructive. The description adds meaningful behavioral context beyond that, including the conditional availability of the full summary ('where this deployment allows it') and a clear exclusion ('Raw transcripts are never returned'). This sets accurate expectations for the agent.

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 front-load the core action and payload, then add a caveat and an exclusion. Every clause earns its place; there is no filler or repetition of structured data.

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 is no output schema, the description does a strong job of enumerating the return contents and setting data-availability expectations. It is slightly incomplete because the videoId parameter semantics are left unexplained, which an agent needs to invoke the tool correctly.

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?

With 0% schema description coverage, the description needed to explain the videoId parameter, but it never mentions it. The property name and the verb 'Fetch one' imply it is an identifier, but the description does not clarify whether it is a YouTube ID, an internal ID, or how to obtain it.

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 specific verb-resource pair ('Fetch one commentary video') and enumerates exactly what is returned: title, channel, thumbnail, UAPDrop page, YouTube URLs, and optionally the full summary, analysis, and talking points. This clearly distinguishes it from siblings like search_videos by noting that search results carry only a truncated preview.

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 when to use it: when you need the full commentary details rather than the truncated preview available in search results. It does not name an alternative tool explicitly or state exclusions, but the contrast with search results provides usable context.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, covering safety. The description adds behavioral context about the 'summary view' and ordering by tier and name, which goes beyond the annotations. It does not mention pagination or return format, but the annotations lift the burden, so a 4 is appropriate.

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?

A single sentence that front-loads the verb and resource, includes scope and ordering, with no fluff. Every word contributes.

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 parameterless list tool with safety annotations and no output schema, the description fully covers what the agent needs: what is listed, its format, and ordering. Nothing critical 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?

With zero parameters, the schema carries no information to clarify. The description does not need to explain any parameters. Per guidelines, 0 params baselines at 4, and the description need not add more.

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 identifies the action (list) and resource (reported non-human entity profiles), specifies it is a summary view, and the ordering. It distinguishes from the sibling get_being by implying a list vs. singular retrieval.

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 this is the tool to list entities but does not explicitly address when to prefer it over search tools or get_being. No exclusions or alternative references provided. It is clear enough for basic selection but lacks explicit routing guidance.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds the useful behavioral detail of newest-first ordering and scopes results to UAPDrop news, but it does not disclose pagination size, rate limits, or return-shape behavior.

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?

One short sentence with no filler; action, resource, and ordering are all front-loaded. It is easy to parse and appropriately sized for a tool of this simplicity.

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 simple one-parameter list tool, the description plus schema and annotations cover the core behavior and safe read-only nature. The lack of explicit pagination semantics and return format is a minor gap given the low complexity, but since no output schema exists, some return-shape ambiguity remains.

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% and the description never mentions the page parameter. The schema's integer/default/min fields make the basic meaning inferable, but the description adds no clarification about paging semantics or how page numbers map to result sets.

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 ('List') with a specific resource ('UAPDrop news articles') and adds a meaningful ordering detail ('newest first'). It is clearly distinct from get_news by virtue of plural listing vs. single retrieval, though it never explicitly contrasts with sibling tools.

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 the tool is for retrieving a paginated collection of news articles, but it gives no explicit when-to-use guidance. It does not mention get_news as the single-article alternative or state when list_news should be preferred over search tools.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, covering the safety profile. The description adds the specific nature of the output (source keys for search_sightings) but does not disclose return format, ordering, or potential pagination. For a zero-parameter read-only tool, this is adequate but not rich.

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?

A single, tightly worded sentence that is front-loaded with the action and resource. There is no filler or redundancy; every word contributes to meaning.

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 simplicity (no parameters, no output schema, trivial read-only operation), the description is sufficient for an agent to understand what it does and why. It could theoretically mention the output type (e.g., 'returns a list of strings'), but that is inferable from the name and purpose. The missing detail is minor.

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?

The tool has zero parameters, so schema coverage is trivially 100%. Per the calibration baseline, a 4 is appropriate when no parameters exist and the description need not compensate for undocumented inputs. The description adds nothing about parameters, but none are needed.

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 states a specific verb ('List') and a specific resource ('archive source keys') with an explicit purpose tied to another tool ('available to search_sightings'). This clearly differentiates it from sibling tools like search_sightings or list_beings, so an agent knows what it returns and why it exists.

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 usage: you list sources to obtain valid keys for search_sightings. However, it does not explicitly state when to use it over alternatives, nor does it provide exclusions or context like 'call before search_sightings'. The link to search_sightings is helpful but insufficient as explicit guidance.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds a small behavioral detail with 'as link-outs', signaling the results are links rather than embedded video files, but it does not disclose ordering, pagination, or the meaning of empty results.

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 short sentence with no filler or redundancy, which is appropriately concise. However, it is a fragment rather than a complete sentence, and the compactness comes at the cost of omitting useful context about parameters and behavior.

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 tool with two parameters, no output schema, and a single-sentence description, important context is missing: what a link-out looks like, how limit affects results, whether the videos are curated or algorithmic, and how this differs from search_videos. The description is too sparse to fully prepare an agent to call the tool correctly.

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 carries the burden of explaining parameters. It never mentions documentId by name (only indirectly implies it through 'related to an archive document'), and limit is entirely absent. The schema's default and minimum values remain the only source of meaning for limit.

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 title 'Find videos related to a document' clearly states the operation and resource, and the description narrows it to 'Commentary videos related to an archive document'. It is not a tautology and is distinguishable from siblings like related_documents, though it overlaps conceptually with search_videos without stating the difference.

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 phrase 'related to an archive document' implies this tool is used when you already have a documentId and want commentary videos tied to it. However, there is no explicit guidance on when not to use it, nor any alternative tool named or compared, leaving the agent to infer the selection logic.

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

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

Annotations already declare read-only and non-destructive behavior. The description adds useful context by mentioning relevance ranking and diversification across release programs, but it does not explain return format, pagination, or the effect of the limit parameter.

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, focused sentence with no wasted words. It front-loads the core action and resource before adding the ranking and diversification details.

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 tool is simple, and annotations cover the safety profile. Still, with no output schema, the description should at least hint at the response shape or the role of limit; both are left to inference.

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. It clarifies that videoId refers to a commentary video, but it gives no meaning to the limit parameter, its default of 3, or how it interacts with the ranking/diversification behavior.

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 what the tool does: find archive documents related to a commentary video. The added ranking/diversification details help distinguish it from siblings like related_commentary or search_documents.

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 intended use is implied: when a user needs documents related to a specific commentary video. However, the description does not explicitly compare against alternatives such as related_commentary or search_documents, nor does it state 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.

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.

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context beyond that: the rationale for excluding VIDEO (generated analysis outranks terse archive records), and the fact that video rows carry a truncated preview that requires a follow-up call to get_video. This explains what the agent can expect from results without speculating.

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 four sentences, each adding distinct information: purpose, default behavior, the VIDEO exception and remedy, and the video-preview note. It is front-loaded with the core purpose and avoids filler. While slightly verbose due to the detailed explanation of the VIDEO exclusion, every sentence earns its place, and the structure is logical and scannable.

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 description covers all major aspects an agent needs to invoke the tool correctly: default kinds, how to override them, the quirk with VIDEO, and the follow-up tool for full video details. It does not mention result ranking or ordering, but that is implied by 'semantic search' and is not critical. Given the tool's moderate complexity (3 params, 1 required) and no output schema, the description is nearly complete; only minor details like result count behavior could be added.

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 only 33%, and the description compensates partially. It explains the semantics of 'kinds' thoroughly, including the default set and how to include VIDEO. However, it does not elaborate on 'query' (beyond implying it's a natural-language text phrase) or 'limit' (though schema has a default and minimum). The description adds some meaning beyond the schema for kinds, but not for the other two parameters, so a 3 is appropriate.

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 states a specific verb and resource: 'Semantic search using embeddings' over the corpus, and explicitly differentiates it from keyword search ('finds conceptually related material that keyword search misses'). It also enumerates the default kinds (declassified documents, news, sighting archive), making its scope unambiguous and distinguishing it from sibling search tools like search_documents or search_sightings.

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 provides clear when-to-use guidance: use it when keyword search misses conceptually related material. It also explains the exact behavior of the 'kinds' parameter, why VIDEO is excluded by default, and how to include it ('Pass kinds:["VIDEO"]'). Finally, it advises routing to get_video for full details, giving the agent a complete usage path.

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

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

Annotations already establish that this is read-only and non-destructive, so the description's burden is lighter. It adds useful context about the consolidated, geocoded dataset and the supported filter dimensions, but it does not disclose pagination behavior, result ordering, or coordinate-format expectations.

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 two sentences, front-loads the resource and provenance, and then lists the key filters. Every clause earns its place, with no filler or redundant restatement of the tool name.

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 9-parameter tool with no output schema and sparse property descriptions, the description gives useful context but omits pagination behavior, coordinate format, and result shape. It is enough to attempt a basic filtered call, but an agent would have to infer or experiment to use pagination or bounding boxes confidently.

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?

With only 33% schema description coverage, the description partially compensates by mentioning date range and bounding-box filters, which gives meaning to the from/to and min/max lat/lon parameters. However, it does not explain page/pageSize semantics, coordinate units, or inclusivity of date bounds, leaving several parameters under-specified.

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') and a precise resource ('consolidated, geocoded UFO/UAP sighting archive'), and anchors it with named sources like NARA, UK National Archives, and CNES GEIPAN. This makes it clearly distinguishable from sibling tools such as search_documents and search_videos.

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 the intended use case: structured filtering over the consolidated sighting archive using date range and bounding-box filters. However, it never names alternatives or states when not to use this tool versus search_semantic or search_documents, so usage guidance remains implicit.

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

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

Annotations already mark the tool as read-only and non-destructive, so the safety profile is covered. The description adds behavioral context beyond annotations: it discloses that results include specific URLs, that the listing preview is deployment-dependent, and that raw transcripts are never returned.

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 leads with the core function and then adds return details and alternative routing in four tight sentences. There is no filler, and each sentence contributes actionable information.

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 read-only search tool with five optional parameters, the description covers return values, deployment-dependent behavior, and sibling routing. The main gaps are the unexplained 'tag' parameter and pagination semantics, making it slightly incomplete but not critically so.

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?

Only 'channel' receives schema documentation, leaving 20% schema coverage, so the description must compensate for the other four parameters. It does not explain 'tag', 'page', 'pageSize', or the exact interpretation of 'query', forcing the agent to guess at pagination and filtering semantics.

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 'Keyword search over indexed UAP commentary videos,' naming the verb, resource, and scope precisely. It also distinguishes itself from siblings by explicitly pointing to get_video and search_semantic, making the tool's unique role clear.

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 tells the agent when to use alternatives: 'Use get_video for the full summary and analysis' and 'For conceptual rather than keyword matching, use search_semantic with kinds:["VIDEO"]'. It also sets a clear boundary with 'Raw transcripts are never returned'.

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