Frenchie

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

Annotations only indicate readOnlyHint=false, openWorldHint=true, idempotentHint=false, destructiveHint=false. The description adds valuable behavioral context: auto-saving to .frenchie/<name>/result.md in stdio mode vs returning inline Markdown in HTTP mode. No contradiction with annotations.

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: the first states the core purpose and file types, the second explains the two transport modes and their output behavior. No fluff, front-loaded, 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 the tool's moderate complexity and that an output schema exists, the description covers purpose, file types, and transport-dependent behavior. It lacks explicit sibling-tool disambiguation, but overall is complete for a straightforward extraction 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 100%, so all three parameters (api_key, file_path, uploaded_file_reference) are already well-documented with transport-specific constraints. The description does not add parameter-level meaning beyond what the schema provides, so baseline 3 applies.

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 extracts structured documents (.docx, .xlsx, .csv, .tsv, .pptx) into Markdown, using the specific verb 'extract' and naming the resource types. This distinguishes it from sibling tools like ocr_to_markdown and transcribe_to_markdown, which handle unstructured content.

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 mode-specific context (stdio auto-saves, HTTP returns inline) but does not explicitly compare to alternatives or state when-not-to-use. Usage is implied by the file-type scope rather than directly contrasted with 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?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context beyond that: the URL is temporary, implying it may expire, which is critical for an agent to know. This goes beyond the structured fields.

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 fluff. The first sentence states the action and result, while the second clarifies the exact use case. It is front-loaded and easy to parse.

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 read-only tool with a known use case, the description is complete. It covers purpose, usage context, and the nature of the output (temporary URL). The output schema (when present) handles return-value details, so 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?

Schema description coverage is 100%, so parameters are fully documented. The description adds meaningful context by explaining that object_key is parsed from a frenchie-result:<objectKey> reference, which reinforces the schema's description. However, it doesn't go far beyond what the schema already states, so a baseline 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 tool's purpose: to get a temporary download URL for a result file. It specifies the resource (result files from OCR/transcription output) and distinguishes itself from siblings by mentioning the frenchie-result: reference, making it 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 gives explicit context for when to use the tool: when an image or file is referenced as frenchie-result: in the result markdown. It doesn't explicitly state alternatives, but the use case is specific enough that an agent can decide appropriately.

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?

Beyond the annotations (readOnlyHint=false, destructiveHint=false, idempotentHint=false), the description discloses critical behavioral details: stdio mode saves to .frenchie/<slug>/generated.<ext>, HTTP mode returns a presigned imageUrl the agent must download, and transparent background is rejected with jpeg. This gives the agent actionable expectations for both invocation modes.

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 with zero waste: the first states the core action, the second lists required/optional parameters, and the third explains mode-specific behaviors. Information is front-loaded and logically ordered.

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 a complete output schema, the description doesn't need to explain return values. It covers the essential mode difference, parameter usage, and a key constraint (jpeg/transparent conflict). The tool is fully contextualized within its sibling set.

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 extra value by summarizing the key parameters and explaining nuances not obvious from the schema: 'style' is merged into the prompt, 'output_dir' is only for stdio mode with a recommendation to use workspace root, and background/format constraints. This elevates it above baseline.

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: 'Generate a single image from a text prompt through Frenchie.' This clearly distinguishes it from sibling tools (e.g., ocr_to_markdown, upload_file) and states the core functionality unambiguously.

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 clearly explains the two operational modes (stdio auto-save vs. HTTP presigned URL) and which parameters are required vs. optional. It doesn't explicitly name alternatives, but the sibling list makes it evident this is the only image-generation tool, so the usage context is clear without redundant exclusions.

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, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds minimal behavioral context beyond 'latest async', such as polling behavior or what happens if the job is still running, but it does not contradict the annotations.

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, front-loaded with the verb and object, and contains no unnecessary words. It is concise and structured for quick reading.

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 an output schema and strong annotations, so the description need not explain return values. However, it misses important usage context such as the fact that the job may still be processing and the result may not be ready, which is critical for an async fetch tool. The description is adequate but not 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 100%, with both job_id and api_key fully described in the input schema. The description itself adds no parameter-specific meaning, but the schema handles the semantics, justifying the baseline score of 3.

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 identifies the resource as 'async Frenchie job result', making the tool's purpose clear. It does not explicitly differentiate from the sibling tool fetch_result_file, but the name and context imply the distinction between job result retrieval and file fetching.

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 offers no guidance on when to use this tool versus alternatives. It does not mention that it should be used after a submission returns 'processing', nor does it exclude use cases. The input schema's parameter description hints at this, but that is not part of the description field.

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 only says 'through Frenchie', implying an external service, but does not disclose behavioral traits such as potential side effects, network usage, or whether files are modified. Annotations indicate readOnlyHint false, but the description adds no further context beyond the raw conversion action.

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 concise sentence, front-loaded with the action and resource, making it easy to scan. It earns its place with no filler, though it could be slightly augmented for behavioral context without losing conciseness.

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 moderate complexity (3 optional params, output schema, annotations), the description is too brief and omits usage guidance, behavioral context, and differentiation from siblings. The schema and output schema cover parameters and return values, but the overall tool context remains incomplete.

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 input schema fully documents all three parameters with detailed descriptions, so the baseline is 3. The description adds no additional parameter semantics beyond what the schema already provides.

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 converts PDF/image files into Markdown, identifying the core action and resource/output format. It mentions 'through Frenchie' indicating an external service, but it does not explicitly contrast with sibling tools like extract_to_markdown or transcribe_to_markdown.

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 no guidance on when to use this tool versus alternatives, nor does it mention prerequisites such as file upload for HTTP transport. The schema covers parameter details, but usage context is entirely absent.

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 indicate readOnlyHint=false and destructiveHint=false, providing minimal safety info. The description adds the behavioral detail that language can be set for accuracy and omitted for auto-detection, which is a useful context but not exhaustive. It does not mention processing behavior, output storage, or dependencies like upload_file for HTTP. Given the annotation coverage, the description adds some value but lacks deeper 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 core purpose and followed by a focused parameter tip. Every sentence earns its place with no unnecessary fluff. The structure is clear and scannable, making it an excellent example of concise writing.

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 rich schema (100% parameter descriptions) and the presence of an output schema, the description doesn't need to explain return values or parameter details. However, it omits the workflow dependency on upload_file for HTTP transport, which is a key contextual aspect for a tool operating in two transport modes. Since this is covered in the schema but not in the high-level description, the completeness is good but not perfect, earning a 4.

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 descriptions for all four parameters, achieving 100% coverage. The description restates the language parameter guidance ('Set language...') without adding new information beyond the schema. The mutual exclusivity/transport-specific behavior of file_path vs uploaded_file_reference is already documented in the schema. Thus, the description adds minimal semantic value beyond the structured 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 converts audio/video files into Markdown transcripts, specifying the input type and output format. This distinguishes it from sibling tools like ocr_to_markdown (likely image-based) and extract_to_markdown (potentially text extraction). The verb 'convert' and explicit resource 'audio/video files' make the 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 for when to use the tool: for audio/video transcription to Markdown. It does not explicitly exclude alternatives or name sibling tools, but the resource type implies the usage. The language parameter hint is practical but not a usage guideline. No when-not-to-use guidance is given, so it falls short of a 5.

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?

It discloses the real workflow: the tool only returns a presigned URL, requiring a subsequent PUT request and passing object_key to the processing tool. This goes beyond the annotations, which only indicate readOnlyHint=false and no destructiveness.

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-loaded with the verb and resource, then a concise follow-up. 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?

The description tells the user exactly what to do before, during, and after the call: get the URL, PUT the file, then pass the key. With an output schema present, return values don't need enumeration. This fully covers the tool's purpose and workflow.

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 documents all four parameters. The description adds context that these parameters are used to generate the presigned upload URL and that the mime_type must match the Content-Type header in the PUT request, providing extra semantic 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's function: obtaining a presigned upload URL for use with specific processing tools in HTTP mode. It distinguishes from siblings by being the upload step, not the processing step.

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 explicitly states the intended context (for use with ocr_to_markdown, transcribe_to_markdown, or extract_to_markdown in HTTP mode) and provides step-by-step instructions for the upload flow. However, it doesn't explicitly mention when not to use it or alternative upload methods.

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