Gemina FileTag

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

With no annotations, the description fully discloses key behavioral traits: automatic currency splitting (noted as 'always split per currency unless a currency filter is given') and that the response meta flags this. This goes well beyond the schema by clarifying edge cases and implicit 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?

The description is concise (two paragraphs) with a clear structure: purpose, optional parameters, example, and a critical note. Every sentence adds value without redundancy. It is front-loaded with the main purpose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity and presence of an output schema, the description covers all necessary input details (metrics, group_by, filters), includes an example, and explains an automatic behavior. It does not need to describe output since an output schema exists.

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 high (75%), but the description adds significant value by explaining the metrics format (list of objects with op and field) and group_by options with concrete examples. The schema's group_by description is vague ('see tool description'), so the description fills that gap. limit is not elaborated, but defaults are in 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 computes aggregate metrics (sums, averages, etc.) over indexed documents, distinct from siblings like query_documents which retrieves raw data. The verb 'Compute' and resource 'documents' are specific, and the operations are enumerated.

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 context for when to use the tool (needing aggregates with optional grouping and filtering) and references query_documents for the same filter structure, implying a complementary role. However, it lacks explicit exclusion of alternatives or a direct comparison to sibling 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 provided, the description fully bears the burden of disclosing behavior. It explains that extraction is asynchronous, that a correlationId is returned for polling, that slots are single-use, and that billing depends on external_id. It also lists optional advanced knobs (model_type, thinking, etc.) and their effects.

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 well-structured with front-loaded purpose and then details. It includes necessary information without being overly verbose, though some parts (e.g., the long list of extraction types) could be streamlined. Still, it earns a 4 for efficiency.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (11 parameters, asynchronous behavior, multiple extraction types, duplicate protection), the description is remarkably complete. It covers the workflow, parameter semantics, and behavior. The output schema exists but is not shown, so the description correctly avoids explaining return values.

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?

Although the input schema describes all 11 parameters (100% coverage), the description adds significant meaning: it explains the file_id lifecycle, enumerates extraction_types options, clarifies the external_id/allow_duplicate interaction, and details the advanced parameters. This goes well beyond the schema descriptions.

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 action ('Run Core-OCR extraction on a previously uploaded file slot') and identifies the resource (a file slot). It distinguishes from sibling tools like 'files_create_upload' and 'get_extraction_result' by referencing the prior upload step and the polling workflow.

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 explicit guidance on when to use the tool: after uploading a file to a slot, and after calling 'files_create_upload'. It covers usage flow, including polling with 'get_extraction_result', and explains the duplicate protection mechanism (external_id) and when to override it (allow_duplicate=true). It also mentions alternatives like 'get_extraction_result' for status checks.

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 provided, so description carries full burden. Discloses that it reserves a slot, returns a URL for PUT, and expects a subsequent 'extract_document' call. Could mention expiration or auth details for completeness.

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?

Concise three sentences with front-loaded key action and clear step-by-step flow. 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?

Given output schema exists and schema coverage is complete, description effectively explains tool's role in the broader extraction flow. Could be slightly more detailed about the output format, but output schema compensates.

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 baseline is 3. Description does not add significant meaning beyond schema; allowed types and max size are already in schema. References downstream 'extraction_types' but not relevant to this tool's parameters.

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?

Clearly states the tool reserves a pre-signed PUT slot for Core-OCR extraction, differentiates from sibling 'files_create_upload', and lists allowed file types and max size.

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?

Provides explicit usage context (Core-OCR flow) and distinguishes from FileTag upload flow. Includes follow-up instructions but lacks explicit when-not-to-use 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?

No annotations are provided, so the description fully carries the burden. It discloses critical behavioral traits: pre-signed PUT, required header echoing, 5-minute expiry, direct GCS upload, and server-side validation at tag_file time for size mismatches.

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?

Single paragraph with key action leading. Every sentence adds value: workflow, constraints, and output details. No redundant or fluff content.

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 complexity (4 parameters, output schema), the description fully covers the workflow (reserve → upload with headers → tag_file), constraints (5 min expiry, 50 MB, allowed types), and output fields (upload URL, headers, expiry, next_tool_call).

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%, providing a baseline of 3. The description adds context: sha256 is optional for verification, filename includes extension, mime_type lists allowed values, and size_bytes is verified later. This enhances understanding beyond 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 'Reserve a pre-signed PUT slot for a forthcoming file upload,' specifying the verb (reserve) and resource (file upload slot). It distinguishes from siblings like 'files_create_extraction_upload' and identifies the next step ('tag_file').

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 this is 'the canonical path for any file the agent holds locally' and that 'bytes never traverse the LLM context.' It mentions allowed types, max size, and the next stage (tag_file). While it doesn't explicitly list alternative tools for when not to use, the sibling context is sufficient for differentiation.

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?

Discloses visibility restriction ('Only documents created by the calling API key are visible') and return content ('including all of its extractions'). Without annotations, this provides moderate transparency, but lacks details on error handling, rate limits, or authentication beyond implicit API key usage.

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 focused sentences with no unnecessary words. First sentence states action and scope, second adds critical access control context. Front-loaded and efficient.

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, the description covers retrieval by ID, included extractions, and access restrictions. Output schema handles return value details, so no further information is needed for competent usage.

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 100% schema coverage, the schema already describes the parameter (UUID). The description adds value by clarifying that the tool returns the document and its extractions, and that visibility is scoped to the caller's documents. This enriches the parameter's meaning beyond 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?

Clearly states 'Fetch one document by its id' specifying the verb and resource. Distinguishes from siblings like get_extraction and query_documents by focusing on single document retrieval, including extractions.

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?

Implies use when a single document ID is known, but does not explicitly state when to use this tool versus alternatives like query_documents or aggregate_documents. No exclusion conditions or alternative suggestions.

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 full burden. It mentions access control (only visible to creator) and that full extracted data is returned, but does not disclose idempotency, error behavior (e.g., if id not found), or any side effects. This is adequate but leaves gaps.

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 main action and includes critical context. It is concise without wasted words. However, it could be structured more clearly (e.g., separating constraints from functionality).

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 simple interface (one parameter, output schema exists), the description covers the main purpose, access constraint, and data content. It omits error details but is sufficient for a retrieval tool with a defined 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?

Schema coverage is 100% and the schema already describes extraction_id as a UUID. The description adds context by specifying the source of the ID (from list_extractions or extract_document), which is helpful but not substantial. Baseline of 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 clearly states the verb 'Fetch' and resource 'extraction', and specifies the id source (list_extractions or extract_document). However, it does not differentiate from get_extraction_result, a sibling tool with a similar name, so the distinction is unclear.

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 explains that only extractions created by the calling API key are visible, which is a key usage constraint. However, it lacks explicit guidance on when to use this tool versus alternatives like get_extraction_result, and does not 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?

With no annotations, the description carries full burden. It discloses polling behavior, status values like IN_PROCESS, and access restrictions. Could mention rate limits or expected polling intervals.

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 purpose, and each sentence provides necessary information without redundancy.

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 output schema exists, the description sufficiently covers polling behavior, status, and access. Could include error states or typical processing time for completeness.

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% and description adds specific context: 'meta.correlationId from the extract response', which aids correct invocation beyond 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 polls for async extraction results, references the specific extract_document call and correlationId, and distinguishes from other tools in the sibling list.

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 explains when to use (after extract_document, polling) and that only the calling API key can see results. It lacks explicit alternatives but the context is sufficient.

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 that the tool reindexes and returns per-outcome counts, including skip reasons. However, it does not explicitly state if the operation is destructive or if it requires any special permissions, leaving some gaps.

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-loading the purpose and usage, then adding context about automatic indexing and return values. Every sentence adds value with no redundancy.

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 one parameter and an output described in the description, the explanation is complete. It covers what the tool does, why it exists, and what to expect as output. No missing information for effective usage.

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 already provides a clear description for the sole parameter ('UUID of a document owned by the calling tenant'). The description adds context ('(Re)index one of the tenant's documents') and usage scenarios, enhancing understanding beyond 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's verb ('index') and resource ('one of the tenant's documents'), and distinguishes it from automatic indexing by calling it a 'manual trigger'. No ambiguity 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?

Explicit use cases are given ('after corrections, or to backfill') and context that indexing normally happens automatically. No explicit alternatives or when-not-to-use, but the manual vs automatic distinction provides clear 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 carries the burden. It discloses that results are newest first, returns summaries, and mentions pagination and filtering. It does not mention side effects, rate limits, or authentication, but these are likely unnecessary for a list operation.

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?

Three sentences, front-loaded with the main purpose, followed by filter and pagination details, then a reference to a sibling tool. No extraneous 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?

Given the presence of an output schema (not shown), the description does not need to explain return values. It covers all operational aspects: ordering, filtering, pagination, and relation to a sibling 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 coverage is 67% (4 of 6 parameters have descriptions). The description adds value by explaining that 'external_id' is the idempotency key, date format is YYYY-MM-DD, and pagination uses skip/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 description clearly states the action 'List', the resource 'document extractions', and the ordering 'newest first'. It distinguishes from sibling tools like 'get_extraction' by noting that this returns summaries and the sibling fetches full data.

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 explicit filtering options and pagination, and tells the user to use 'get_extraction' for full extracted data. It does not explicitly mention when not to use this tool, but it implies the appropriate 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?

With no annotations, description carries full burden. It discloses that only indexed tenants' documents appear, output includes matched docs with fields and scores. Does not mention rate limits or destructive behavior, but as a read-only search, the key constraints are covered.

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 focused paragraph, front-loaded with purpose, then modes, output, and limitation. Every sentence adds value without redundancy.

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?

Comprehensive for a search tool: explains modes, output, and indexing prerequisite. Output schema exists, so return details are covered. Lacks explicit error handling or pagination depth, but sufficient for agent selection.

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 50%. Description adds meaning for mode (explains each) and indirectly for text, but skip, limit, top_k lack description in both schema and description. Filters and mode descriptions partly compensate but not fully.

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?

Description clearly states the tool searches an indexed document collection, with specific verb 'Search' and resource. It distinguishes from sibling tools like aggregate_documents, index_document, and tagging tools by focusing on 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?

Provides guidance on when to use each mode (structured, semantic, hybrid) and recommends hybrid as default for free-text questions. Does not explicitly contrast with siblings, but the purpose is clearly search-oriented, so usage context is 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?

With no annotations, the description carries full behavioral disclosure. It specifies the data key format in detail, explains the return value (per-field comparison summary), and notes the one-time feedback constraint. This is good, though it could add information on error handling or idempotency.

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, consisting of two sentences plus a code example. Every sentence adds value: purpose, data format, constraint, and return summary. No extraneous content.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (2 required params, output schema present), the description covers the essential aspects: purpose, parameter format, usage constraint (once per extraction), and return value. It is mostly complete, though could mention what happens on duplicate submissions.

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 baseline is 3. The description adds significant value beyond the schema by providing the exact format for data keys (e.g., 'label:Total Amount|ptr:/totalAmount') and an example. This clarifies how to construct the input, surpassing the schema's generic description.

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 purpose: to submit verified/corrected field values for a completed extraction, establishing the extraction-quality feedback loop. It uses a specific verb (submit) and resource (field values), and the context distinguishes it from sibling tools like get_extraction, which only retrieve data.

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 mentions a key constraint: each extraction accepts feedback once. This provides clear context on when to use the tool and its limitation. However, it does not mention when not to use it or compare to other tools, though no direct alternative exists among siblings.

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 provided, so description carries full burden. It details validation (size, content-type, SHA-256), atomic consumption, extraction pipeline, return fields, and single-use slot. Could mention error conditions but is otherwise thorough.

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?

Three sentences, front-loaded with main action, every sentence contains critical information: purpose, process, and actionable instruction. No fluff.

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 annotations and an output schema likely referenced, the description covers the full workflow: input, validation, processing, output fields, and post-action. Single-use note prevents misuse.

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 covers 100% of parameters. Description adds value for file_id by explaining its source and prerequisite (after PUT). For end_user_id and external_id, description repeats schema info but reinforces optionality.

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 runs the FileTag pipeline against a previously uploaded slot, specifying the source of file_id and distinguishing it from siblings like files_create_upload.

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?

Provides clear context: file_id from prior upload, validation process, and a next_action instruction. Lacks explicit when-not-to-use or alternatives, but context is sufficient for correct invocation.

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 fully discloses behavioral traits: SSRF guards (HTTPS only, no private IPs, 30s timeout, 50MB cap, redirects disabled), return structure including next_action recipe, and the instruction to act on the result unless user asked for metadata only.

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, dense paragraph that front-loads the core purpose, then efficiently covers constraints, return value, and usage guidance. Every sentence adds value without redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (server-side fetch, SSRF guards, return structure with enriched_file_url and next_action), the description is complete. It covers all necessary information for an agent to correctly select and invoke the tool, even without seeing the 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?

Schema coverage is 100% but the description adds critical context beyond schema: URL must be public HTTPS, redirects not followed, and agents must resolve them. It also explains the optional parameters' usage in the broader context of the pipeline.

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 remote URL and runs the FileTag pipeline server-side. It distinguishes from siblings like 'tag_file' by emphasizing that this tool is for files at public URLs and that bytes never traverse LLM context.

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 says 'Use this when the file already lives at a public URL.' Also provides guidance on when not to act (if user asked for metadata only) and mentions alternative behaviors like resolving redirects before invoking.

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