UAPDrop Research Archive

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

With no annotations, the description must carry the full burden of behavioral disclosure. It adds value by mentioning that every claim is backed by a citation, and the word 'fetch' implies a read-only operation. However, it does not specify whether authentication is required, how large the response might be, or whether it can fail for missing slugs, leaving gaps in transparency.

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-loaded with the primary action, and contains no extraneous words. Every sentence earns its place: the first defines the operation, the second clarifies the citation guarantee.

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 with one parameter and no output schema, the description covers the core functionality but omits details about the response structure and how the slug maps to a specific being. Given the existing sibling tools and lack of annotations, the description is adequate but leaves some contextual gaps, especially regarding expected output format.

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 only one required parameter 'slug' with no description, and schema coverage is 0%. The description does not mention 'slug' at all, failing to explain what it represents or how to construct it. Since the description must compensate for the lack of schema detail and does not, it adds minimal value beyond the parameter name itself.

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 tool fetches a single entity profile with a cited references ledger, using the specific verb 'fetch' and the resource 'entity profile'. This distinguishes it from sibling tools like list_beings or get_document, as it focuses on an individual entity with its full citation trail.

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 when you need a detailed entity profile with citations, but provides no explicit comparison to alternatives like search_documents or list_beings. It does not state when not to use this tool or mention any prerequisites or exclusions, making the usage guidance only 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?

With no annotations provided, the description carries the transparency burden. It discloses that the tool returns the full document including attachment gallery, and conveys the constraint that externalId requires releaseProgram. While it doesn't mention errors or authorization, the read-only behavior and key constraints are effectively communicated.

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, well-structured sentence conveys the primary action, scope, and identifier requirements without wasted words. It is front-loaded with the verb and object.

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 sufficiently complete: it names the resource, specifies return content (full document + attachments), and how to identify the target. It doesn't address error cases or auth, but these are less critical given the tool's simplicity and lack of an output schema.

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?

Though the schema descriptions cover 100% of parameters, the description adds critical cross-parameter logic: 'either id, or both releaseProgram and externalId'. This is not inferable from individual parameter descriptions and significantly clarifies valid invocation patterns.

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 resource ('archive document'), and explicitly notes it includes the attachment gallery. This clearly distinguishes it from sibling tools like get_news or get_video.

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 explicit guidance on parameter usage: 'Supply either id, or both releaseProgram and externalId.' This clarifies the valid identifier combinations. It does not explicitly discuss alternatives, but the context of fetching a single document is clear and distinct from 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?

With no annotations, the description carries the transparency burden. It discloses that the tool returns the article 'in full' and includes related-commentary links, which is useful. However, it does not mention error handling, authentication, or what 'in full' entails beyond that (e.g., format, metadata). 'Fetch' implies read-only, but this is not explicitly stated.

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, front-loaded sentence that clearly states the core action and a key feature. No filler or redundant 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 simple tool with one required parameter and no output schema, the description gives an idea of what is returned ('full article' and 'related-commentary links') but lacks detail on return format, possible errors, or how the response is structured. It is adequate but not thorough.

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 does not mention the newsId parameter at all, leaving the agent to infer its purpose from the parameter name. There is no explanation of how to obtain the newsId or its expected format.

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 resource ('one news article'), and explicitly states it includes related-commentary links. This distinguishes it from sibling tools like list_news (which likely lists multiple articles) and related_commentary (which focuses only on links).

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 full single news article by ID, but it does not explicitly state when to use it over alternatives like related_commentary or provide exclusion criteria. The usage context is clear from the wording ('Fetch one news article') but not fully articulated.

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?

With no annotations provided, the description carries the burden of behavioral disclosure. It adds context like 'full media set' and the composite key, but it does not specify error handling, authentication requirements, or whether the record is returned in a specific format. This is adequate for a simple read but lacks depth.

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 sentence that packs all key information—action, resource, keying mechanism, and return contents—without unnecessary words. It is front-loaded and immediately understandable.

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 simplicity of the tool (two string parameters, no output schema, no annotations), the description covers the essential aspects: what it fetches, how it identifies the record, and what is included. It lacks some context like typical error cases, but for a straightforward get operation in a family of similar tools, this is reasonably complete.

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 provides only names and types with no descriptions (0% coverage), so the description must compensate. It does connect the two parameters as a composite key ('keyed by source and external id'), which gives them semantic meaning beyond the schema. However, it does not elaborate on allowed values or formats for either parameter.

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 tool fetches a single sighting record with its full media set, using a specific verb ('Fetch') and resource ('sighting record'). It also specifies the keying mechanism ('source and external id'), which distinguishes it from sibling getters for other entity types like get_being or get_document.

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 when you have a specific source and external ID to retrieve a single sighting. However, it does not explicitly state when to prefer this over search_sightings or list_sightings, nor does it mention any exclusions or alternatives.

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?

No annotations are provided, so the description carries the full burden. It discloses important behavioral traits: full summary/analysis/talking points are 'where this deployment allows it,' and raw transcripts are 'never returned.' These are substantive constraints beyond the schema.

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 packs a lot of information without being bloated. The dash effectively contrasts full data with truncated search previews, and the transcript exclusion is a clear final clause. Well-structured and 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?

Given no output schema and no annotations, the description covers expected return fields, the conditional nature of summaries, and the transcript limitation. It leaves out parameter semantics and response format, but for a simple single-resource fetch, it provides enough context to set expectations.

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 says nothing about the videoId parameter, its format, or whether it is a YouTube ID or internal ID. The agent gets no guidance beyond the parameter name, which is insufficient for low schema coverage.

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 begins with 'Fetch one commentary video' – a specific verb and resource. It clearly enumerates what is returned (title, channel, thumbnail, URLs, summary, etc.) and contrasts with search results, distinguishing it from siblings like search_videos and 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 description implies when to use this tool by contrasting with search results: 'search results carry only a truncated preview.' It also notes a deployment-dependent condition for full summaries. However, it does not explicitly name alternatives or state when not to use it.

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?

No annotations are provided, so the description carries the behavioral disclosure burden. It adds useful information about ordering ('by tier then name') and the summary nature of the view, but it does not explicitly state whether the operation is read-only or mention any side effects or security considerations.

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, front-loaded sentence that conveys the verb, resource, scope, and ordering without any filler. 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?

Given the tool's low complexity (no parameters, no output schema), the description adequately covers the core purpose and ordering. It leaves the exact fields of the summary view undefined, but this is acceptable for a simple list tool with sibling context.

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 per the rubric a baseline of 4 is appropriate. The description adds no parameter information, but none is 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 clearly states the tool lists 'reported non-human entity profiles' in a summary view, with a specific verb 'List' and resource. It distinguishes itself from sibling tools like get_being (single entity) and list_news (news items) by explicitly describing the list scope and ordering.

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 gives clear context that this is a list operation for all entities, implying it is for overview purposes. However, it does not explicitly mention alternatives such as get_being for individual profiles, so it lacks a direct exclusion or when-not 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?

With no annotations, the description must disclose behavioral traits itself. It mentions 'newest first' ordering but does not state whether the operation is read-only, explain pagination behavior despite a page parameter, or describe the response format. This leaves significant behavioral unknowns.

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, front-loaded sentence: 'List UAPDrop news articles, newest first.' It is concise and every word contributes useful information without unnecessary elaboration.

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 list tool, the description gives the core purpose and ordering, but it is incomplete because it omits pagination details, return format, and any guidance on choosing this over the get_news sibling. The presence of a page parameter and a close sibling tool suggests more context would be valuable.

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 page parameter is not mentioned in the description. Schema description coverage is 0%, and the description does not compensate by explaining that page controls pagination; the schema alone (with default and minimum) provides minimal meaning, but the description adds no 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 it lists UAPDrop news articles and specifies ordering as 'newest first,' making its purpose specific and distinct from sibling tools like get_news, which presumably fetches a single article.

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 its use for obtaining a collection of news articles, but it does not explicitly mention when to use it versus get_news or other list tools. No exclusions or alternatives are provided, so usage guidance is only implied, not clearly stated.

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?

With no annotations, the description must carry the behavioral burden. It clearly indicates a read-only list operation, adds context about the keys being for search_sightings, and has no contradictions, but does not disclose return format or edge cases beyond the implied list.

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 sentence, nine words, front-loaded with the action verb and resource. Every word is purposeful.

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, no-output-schema tool, the description fully captures the purpose and context. No additional information is necessary to understand its function.

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 the schema is fully defined. The description does not need to add parameter semantics, hitting the baseline of 4.

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') and clearly identifies the resource ('archive source keys') and its relationship to 'search_sightings,' distinguishing it from other list/search tools in the sibling set.

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 implicitly directs use before search_sightings by identifying the keys it makes available, but does not explicitly state when not to use it or mention alternative 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?

With no annotations, the description is the sole source of behavioral disclosure. It only reveals that results are 'link-outs' (external links), which is useful but insufficient. It does not state whether the operation is read-only, what response structure to expect, pagination behavior, or error handling.

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, efficient sentence that is front-loaded with the key concept. It avoids unnecessary fluff, but it is so brief that it leaves significant gaps in usage and parameter understanding. It earns its place but could have been expanded while still remaining concise.

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 2 parameters, no annotations, and no output schema, the description is insufficient for correct invocation. It lacks parameter semantics, usage alternatives, and any behavioral detail beyond 'link-outs'. An agent would not know what response to expect or how to handle edge cases like missing related videos.

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 adds no parameter semantics. It does not explain how 'documentId' is used or what 'limit' controls beyond the schema's basic type/default. The tool name and description imply documentId is the target, but no explicit mapping or usage context is provided.

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 resource as 'commentary videos linked to an archive document' and the format as link-outs. This distinguishes it from sibling tools like related_documents (which likely returns other documents) and search_videos (general video search). The absence of an explicit verb (e.g., 'retrieve') is a minor weakness, but the intent is unambiguous.

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 does not state when to use this tool instead of alternatives, nor does it mention any exclusions or prerequisites. It gives no context about how it differs from related_documents or search_videos. The only implied usage is that it takes a documentId, but no explicit guidance is provided.

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?

The description discloses the ranking by relevance and diversification across release programs, which are useful behavioral traits. However, with no annotations, it does not address return format, authentication, or side effects, leaving a significant transparency gap for a tool that might be mistaken for an archiving mutation.

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 sentence that front-loads the core purpose and is free of filler. The word 'Archive' is slightly off but does not hurt readability significantly.

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 has only two parameters and no output schema or annotations, the description should at least explain the role of limit and the nature of the response. It lacks these details, making it barely adequate for reliable invocation.

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% and the description does not mention either parameter (videoId or limit). It only refers to 'commentary video' without explicitly mapping to videoId, and limit is entirely absent, so the description fails to add any parameter meaning.

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 tool returns documents related to a commentary video, with specific ranking and diversification behavior. This differentiates it from siblings like search_documents or related_commentary, though the verb 'Archive' is slightly unconventional and could be misread as a write operation.

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 when you have a commentary video and need related documents, but it provides no explicit guidance on when to choose this over sibling tools such as search_documents or related_commentary, nor any exclusions or alternative recommendations.

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?

With no annotations, the description carries full transparency burden. It discloses what is searched (title, summary, incident text, tags, extracted PDF text) and the scope (declassified UAP/UFO document archive). It does not disclose behaviors such as empty-query handling, result ordering, or rate limits, but it provides meaningful behavioral context for a search tool.

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 redundancy. It front-loads the purpose, adds search scope in the second sentence, and gives usage alternatives in the third. Every sentence earns its place, making it highly concise and well-structured.

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 search tool with no output schema, the description explains coverage and limitations well but omits return-value details (e.g., what fields each result contains) and pagination behavior. The absence of output schema means the description should ideally disclose what the tool returns, which it does not. This makes it adequate for tool selection but not fully complete.

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 description partially compensates by clarifying that the query parameter searches title, summary, incident text, tags, and extracted PDF text. However, it does not explain the page and pageSize parameters, which lack schema descriptions, leaving some parameter semantics under-explained.

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 and resource: 'Full-text search of the declassified UAP/UFO document archive.' It further distinguishes from siblings by explicitly stating it covers documents only and directing to search_videos for video content. This is a clear, specific purpose with strong sibling differentiation.

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 gives explicit when-to-use guidance: 'Covers documents only: witness interviews, documentaries and commentary live in the video corpus — run search_videos as well when researching a person, incident or topic.' It tells the agent to use this tool for document searches and to complement with search_videos for broader research, which is clear and actionable.

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?

With no annotations provided, the description fully discloses behavioral traits: it explains why videos are excluded by default, that video rows carry truncated previews, and that get_video provides the full summary. This goes beyond schema and gives the agent useful operational context without contradicting any structured data.

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?

Four concise, well-structured sentences that front-load the core purpose, then cover defaults, exception handling, and output behavior. No filler or redundant information—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?

Despite lacking an output schema and annotations, the description provides a complete operational picture: default search scope, how to include optional kinds, the ranking behavior rationale, and how to get full results for video. It is sufficiently complete for the agent to decide when and how to invoke the tool.

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%, but the description compensates significantly by explaining the kinds parameter in depth (defaults, explicit VIDEO inclusion, mixing kinds). It also enriches the query parameter meaning by describing semantic embeddings. However, the limit parameter is not mentioned in the description, so some param semantics are still left to the schema.

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 tool performs semantic search using embeddings, which distinguishes it from keyword-based sibling tools like search_documents. It also specifies the default scopes (declassified documents, news, sighting archive) and the optional VIDEO kind, providing a precise verb+resource definition.

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 contrasts with keyword search ('finds conceptually related material that keyword search misses') and explains when to include VIDEO via kinds:["VIDEO"]. It also gives the rationale for exclusion (generated analysis outranking archive records) and points to get_video for full details, serving as a clear when-to-use versus alternatives.

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?

With no annotations, the description must disclose behavior. It mentions the archive source and filter types, which is useful context, but it does not explain pagination behavior, default results, result ordering, or response format. This is a minimal level of transparency, lacking operational details.

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 exceptionally concise: two short sentences that front-load the core purpose (search archive), then add filter capabilities. Every phrase earns its place, with no redundancy 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 tool has 9 parameters, no output schema, and no annotations, yet the description only covers high-level search purpose and two filter types. It omits pagination, source selection details, default behavior, and any indication of what results look like. This is incomplete for a tool of this complexity.

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% (to, from, source have descriptions). The description mentions 'date range and bounding-box filters', which helps explain from/to and the lat/lon parameters, but it fails to mention pagination params (page, pageSize) or the source parameter behavior. With 9 params and low schema coverage, the description insufficiently compensates.

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 a specific verb ('Search') and resource ('the consolidated, geocoded UFO/UAP sighting archive'), and further specifies the data sources and supported filters. This clearly distinguishes it from sibling tools like get_sighting or search_semantic, making the tool's purpose unambiguous.

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 context: it indicates the tool searches a specific consolidated archive with date range and bounding-box filters, implying use for structured filtering across sightings. It does not explicitly name alternatives or exclusions, but the scope is clear enough for an agent to infer when to use it.

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?

With no annotations, the description carries the full burden. It discloses return fields (UAPDrop URL, YouTube URL, listing preview), a conditional behavior ('where this deployment allows it'), and the raw transcript prohibition. Could add more on pagination or sorting, but it's reasonably transparent.

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 concise, front-loaded with the purpose, and logically organized: what it does, what it returns, limitations, and alternative tools. 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 5 parameters, no output schema, and no annotations, the description provides solid context: return types, conditional preview behavior, raw transcript prohibition, and alternatives. It lacks details on pagination or default ordering, but overall it's sufficiently complete for a search tool.

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 the 'channel' parameter has a schema description (20% coverage). The description doesn't explain 'tag', 'page', 'pageSize', or 'query' semantics beyond the general keyword-search context. It fails to compensate for the schema coverage gap.

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 tool's function: 'Keyword search over indexed UAP commentary videos.' It also differentiates from siblings by mentioning get_video for full summaries and search_semantic for conceptual matching.

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 states 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"]'. Also notes a limitation: '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.