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

With no annotations, the description carries the full transparency burden and does so thoroughly: it discloses local input file constraints, output directory and non-overwrite guarantee, return values (saved path and temporary source URL), and the quota side effect (100/month). These are exactly the behavioral details an agent needs 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?

The description is well structured, front-loading the purpose and the critical ordering guidance, and each sentence adds value. However, it repeats some schema details (e.g. PNG/JPEG/WebP, 25MB) that are already present in the images parameter description, causing mild 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?

For a tool with no output schema, the description provides the needed operating context: it documents what inputs are accepted, what the tool does to them, where results are stored, that outputs are not overwritten, and the return value. this is sufficient for an agent to invoke the tool correctly without guessing.

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 the baseline is 3. The description does add a little semantic context (e.g. reference file formats and the result, output name) but largely duplicates schema information like file types and size limits. It does not provide deeper meaning beyond the schema, so a 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description starts with a specific verb-resource pair ('Transform existing images with flux-2-klein image-to-image') and immediately distinguishes from the sibling tool by telling the reader to 'Use generate_image instead when starting from text alone.' The agent can tell exactly what this tool does and how it differs from its closest sibling.

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 guidance by naming the alternative tool and giving the exact condition for choosing it: 'Use generate_image instead when starting from text alone.' This clearly tells the agent when not to use this tool. The description also indirectly grounds when to use it (when existing images are available to transform).

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 behavioral burden and succeeds admirably. It discloses the non-obvious behavior that the tool returns only a summary (item count, dimensions, input tokens), not the vectors themselves, and explains why (vectors too large for conversation). It also cautions the agent to use this for populating a store rather than reading values, which prevents a classic misuse.

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 dense sentences that each earn their place: the first establishes purpose and sibling relationship, the second explains the surprising return behavior and gives a usage directive. The key purpose is front-loaded, and there is no 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?

For a two-parameter tool with no output schema and no annotations, the description covers everything an agent needs to call it correctly: purpose, model, dimension, return shape (summary fields), batch guidance, and the follow-up sibling. The lack of an output schema is compensated by explicitly enumerating the returned summary fields.

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 schema documents both parameters. The description adds genuine value beyond the schema by explaining that batching strings in one call is cheaper, which informs how the 'input' parameter should be used. Encoding_format is already fully covered by the enum and default, and the description adds nothing needed there.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb ('Turn text into...vectors'), names the exact model (qwen3-embedding), gives the output dimension (4096), and declares the use case (RAG or semantic search). It also differentiates itself from sibling rerank_documents by positioning it as the subsequent ordering step, so there is no ambiguity about what this tool does.

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 RAG or semantic search, and to populate a vector store rather than read values. It also explains the relationship to the rerank_documents sibling ('then orders whatever a search over those vectors brings back'). It does not explicitly state when not to use it or name an alternative for the same job, so it stops 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?

Since no annotations are provided, the description carries the full burden of behavioral disclosure. It explains output directory (NAN_OUTPUT_DIR), the never-overwrite naming behavior (appending -2, -3), the return value (saved path and temporary URL), and quota implications (100/month). It does not mention rate limits or auth, but the disclosed behaviors are substantial and go beyond simple statements.

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 long, highly efficient, and front-loaded. The first sentence states the core function, the second provides routing guidance and key operational details (output path, overwrite behavior, return value, quota). Every clause earns its place 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's moderate complexity (six parameters, but all well-documented in the schema) and the absence of an output schema, the description provides complete context: what it does, when to use it, where outputs are saved, how naming conflicts are handled, what is returned, and quota impact. Nothing an agent needs to invoke it correctly 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?

The input schema has 100% description coverage for all six parameters, so the baseline is 3. The description does not add significant new meaning beyond the schema; it merely repeats that each generated image counts against the quota (already stated in the n parameter) and that output names are sanitized (already in outputName). This is adequate but not additive.

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 primary function: generating an image from a text prompt using a specific model (flux-2-klein). It uses a specific verb ('generate'), a specific resource ('image'), and names the input (text prompt). It also distinguishes itself from the sibling tool edit_image by explicitly stating when edit_image should be used instead, which differentiates the purpose.

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 states when to use this tool versus the alternative: 'Use edit_image instead when you already have reference images to transform.' This provides clear routing guidance and leaves no ambiguity about which tool to select for different scenarios.

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 the output format (one per line with owner), the scoped result set (models the configured key can reach), and the implied read-only nature of listing.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two short, purposeful sentences. The action and output format are front-loaded, and the use case is stated without any 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?

For a simple parameterless list tool with no output schema, the description covers access scope, return format, and purpose. Nothing needed to invoke the tool correctly 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?

There are zero parameters, so the schema is trivially complete and the baseline is 4. The description adds no parameter information because 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?

States the specific action: list the model IDs the configured key can reach, one per line with its owner. This clearly distinguishes it from sibling tools like list_voices by focusing on model availability.

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 for when to use the tool: to confirm access or spot a retired model before calling another tool. It doesn't name explicit alternatives, but the sibling tools cover different domains, so the intended usage is unambiguous.

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 of behavioral disclosure. It explicitly notes that the answer comes from a bundled catalog, incurs no API cost, and requires no arguments—this is beyond the basic purpose. It does not elaborate on return format beyond grouping, but for a simple list operation this is sufficient.

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, well-structured sentence that front-loads the purpose, then adds the behavioral/cost detail. Every clause earns its place; there is no filler or 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?

For a zero-parameter, read-only-like tool, the description covers all essential aspects: what the tool lists, how results are grouped, where data comes from, and that it is free of arguments and API cost. Without an output schema, the description still gives the agent enough to make a correct 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?

There are zero parameters, so the schema covers everything. The description adds clarity by explicitly stating 'takes no arguments,' which prevents any guesswork about optional fields. This meets the baseline for 0-parameter tools and adds a small user-oriented confirmation.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb ('List'), the precise resource ('kokoro voice ids that text_to_speech accepts'), and the grouping ('by language'). It clearly distinguishes itself from sibling tools like list_models or text_to_speech by scoping the subject to voice IDs used by text_to_speech, so an agent knows exactly what it returns.

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 usage context: it costs no API call and takes no arguments, which tells an agent when it is safe/cheap to call. However, it does not explicitly name alternatives (e.g., list_models) or state when not to use it, though the context strongly implies it is for discovering voice IDs for text_to_speech.

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 disclosing behavior. It mentions the underlying model (Qwen3-Reranker-8B) and the output format (one line per document with relevance score and position), which adds value beyond the schema. However, it does not disclose potential rate limits, error handling, or whether the input order is preserved in case of ties. The description provides average behavioral detail for a tool with no 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 reasonably concise and front-loaded with the main purpose. It introduces the RAG pipeline context and the output format in a few sentences. There is minimal redundancy; each sentence earns its place. The description could be slightly trimmed, but it remains well-structured and informative.

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 (3 parameters, no output schema) and the rich schema coverage, the description provides sufficient context for an agent to invoke it correctly. It explains the tool's role in the pipeline, the output format, and parameter semantics. The absence of an output schema is mitigated by the description's return value explanation. Minor gaps include missing error behavior or edge cases, but overall it is complete enough.

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 the schema already documents all three parameters: query, documents, and top_n. The description adds context about the 'documents' parameter by noting it's typically the top hits of a vector search, which is helpful but not extensive. Since the schema is thorough, a baseline of 3 is appropriate; the description adds marginal value 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 purpose: ordering documents by relevance to a query using a specific reranker model. It identifies the resources (documents, query) and the action (rerank), and distinguishes it from sibling tools like embed_text and search-related tools. The context of being part of a RAG pipeline further clarifies its role.

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 this tool: as the second half of a RAG pipeline, after embed_text builds vectors and search returns hits. It mentions the relationship to embed_text, but does not explicitly state when NOT to use it or name alternative reranking tools. The usage is implied strongly, yet lacks explicit alternatives or 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?

With no annotations, the description fully carries the burden. It discloses the local file requirement, size/time limits and timeout risk, the return format (plain transcript vs. verbose JSON with per-segment timings), and explicitly states 'Writes nothing to disk'—a critical side-effect disclosure.

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 concise sentences front-load the core purpose and key constraints. The statement about text_to_speech is placed early and each remaining sentence covers a distinct necessity 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?

For a tool with only three parameters, no output schema, and no annotations, the description covers all essential calling information: file existence and size/time limits, output behavior, and side effects. 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?

The input schema already provides 100% coverage with clear descriptions for each parameter (file path, verbose, language). The description adds slight extra context (verbose returns per-segment timings) but doesn't meaningfully enhance parameter 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 uses a specific verb ('Transcribe') with a clear resource ('a local audio file') and explicitly contrasts with the sibling tool ('text_to_speech does the opposite'). This makes the tool's distinct role unmistakable.

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 conditions for use: the file must exist on this machine, be under 25MB and ~2 minutes, or the request times out. It also names the alternative (text_to_speech) for the opposite operation, giving clear when-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 carries the full burden of behavioral disclosure. It clearly states the tool writes audio under NAN_OUTPUT_DIR (default ~/nan-mcp-output), does not overwrite existing files, and returns the saved path and size in bytes. It does not mention auth, rate limits, or other API caveats, but the write-safe behavior is a meaningful and useful disclosure.

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 no redundancy: the first states purpose and sibling distinction, the second gives a prerequisite, and the third covers output location, overwrite policy, and return value. 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?

The tool has 5 parameters (1 required), no output schema, and no annotations, so the description must carry context. It covers purpose, prerequisite, output location, overwrite behavior, and return value. Minor omissions like file extension handling and error conditions exist, but the rich schema plus this description are sufficient for a correct 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 description coverage is 100%, so the baseline is 3. Each parameter already has a clear description, including the voice parameter with concrete examples. The description adds no additional parameter-level detail beyond the prerequisite to call list_voices, which is usage guidance rather than parameter semantics.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb ('Synthesize'), a clear resource ('speech from text'), and names the underlying engine ('kokoro (NaN API TTS)'). It also explicitly differentiates from the sibling 'speech_to_text' by saying it 'does the opposite', so an agent can confidently pick between the two.

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 concrete, actionable guidance: call list_voices first to choose a voice id, and clarifies that speech_to_text is the opposite direction. This is an explicit alternative/routing instruction rather than leaving the agent to infer when to use the tool.

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