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

With no annotations, the description carries the full behavioral burden but does disclose the key output contract: files are saved locally and their paths are returned. It says nothing about credentials/API key needs, latency, cost, rate limits, or failure modes, which are real concerns for a generation call against an external bot service.

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 tight sentences: purpose first, then the editing case, then the output behavior. Every clause carries information an agent needs; 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 7-parameter tool with no output schema, the description covers the action, model selection, reference-image editing, and the return shape (saved paths). It could go further on auth requirements and on how `parameters`, `aspect_ratio`, and `prompt_flags` should be chosen between, though the schema's 100% coverage mitigates that.

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, but the description adds value beyond the schema: it names the default model (GPT-Image-1), lists concrete alternative bot names matching the `model` param, and clarifies that reference_images are for editing/remixing rather than just 'use as reference'.

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 a specific verb+resource ('Generate an image from a text prompt'), names the default model and several alternatives, and the local-save behavior. It is clearly distinguishable from generate_video, generate_speech, and generate_music.

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?

Gives usable selection guidance ('Pass reference_images to edit or remix existing pictures') and names the default bot when no model is supplied. It stops short of saying when to prefer this over the generic sibling generate_with_poe_bot, so there is no explicit alternative routing.

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 behavioral burden. Beyond naming the default bot (Lyria) it says nothing about authentication, cost/rate limits, latency, whether generation is synchronous, or what happens when model/parameters are omitted or a flag is ignored. The 'Use when a bot ignores parameters' note lives in the schema, not here.

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 action and bot default, and the parenthetical model list is compact. The second sentence duplicates the schema's prompt description, which is the only wasted space.

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 six-parameter, nested-object tool with no annotations and no output schema, the description leaves meaningful gaps: it never explains the relationship between duration_seconds, prompt_flags and parameters, does not mention where generated files land (output_dir), and does not indicate what the caller receives back. It is adequate to start a call 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%, so the schema already documents all six parameters, establishing a baseline of 3. The description adds one genuinely new fact — the default model is Lyria and which alternatives exist — but its prompt guidance simply restates the schema's 'Genre, mood, tempo, instruments' wording and adds no format or interaction details for parameters/prompt_flags/duration_seconds.

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 a specific verb and resource ('Compose music or sound from a text prompt') and names the bot family it targets (Poe music bots, default Lyria), which separates it from generate_image, generate_video and generate_speech. It does not, however, clarify how it differs from the generic sibling generate_with_poe_bot, which sounds like it could also reach a music bot.

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?

Usage is implied rather than stated: the reader infers this is the tool to pick when music or sound is wanted. There is no explicit when-not guidance, no prerequisite (Poe auth/credits), and no routing rule versus generate_with_poe_bot or list_poe_models, so selection still requires inference.

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 at all, the description carries the full burden. It does disclose the key side effect ('Saves an audio file locally'), which is real behavioral value for a write-to-disk tool, but it says nothing about auth (Poe API key), network/rate-limit behavior, cost, or text-length limits.

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 tightly packed sentences with zero filler; the core action and its output location lead, and the model options follow as supporting detail.

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 6-parameter tool with a nested `parameters` object, no output schema, and no annotations, the description covers the primary output (a locally saved audio file) but leaves the caller without auth prerequisites, failure modes (unsupported bot/voice), or any indication of what is returned on success.

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, but the description genuinely adds meaning the schema lacks: the default model ('default: ElevenLabs') and additional valid bot names (Hailuo-Speech-02, OpenAI TTS) beyond the schema's two examples. It does not clarify `voice` behavior when a bot lacks voice selection.

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 gives a specific verb+resource pair ('Turn text into spoken audio') and names the concrete backend family (Poe TTS bots, default ElevenLabs). The output modality implicitly separates it from generate_image/generate_video/generate_music, but it never explicitly differentiates itself from the general-purpose sibling generate_with_poe_bot.

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?

Usage is only implied: use this when you want speech from text. There is no when-not guidance and no statement about when to prefer this over generate_with_poe_bot, even though both talk to Poe bots. The bot-name list gives model-selection guidance but not tool-selection 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 discloses the crucial latency trait ('Video can take several minutes'), the default model, and the image-to-video mode — genuinely useful operational context an agent can plan around. It still omits what the call returns (file path, URL, or status) and failure/timeout behavior, which matters more given there is no output 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?

Three compact sentences, front-loaded with the core action and scope, then capability options, then the latency warning. No filler and nothing buried.

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 an 8-parameter tool with no annotations and no output schema, the description covers the primary concepts but leaves the agent guessing about the return artifact (saved file location/format versus a URL) and how parameters, aspect_ratio, and prompt_flags interact when a bot supports only some of them.

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% and the parameter descriptions are already rich, so the description mostly echoes them ('Optionally animate a start image' restates the start_image param). It adds the model roster beyond the schema's examples, but no new semantics for parameters, parameters, aspect_ratio, or prompt_flags.

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 a specific verb and resource ('Generate a video clip from a text prompt') plus the mechanism ('with a Poe video bot'), which immediately separates it from generate_image, generate_speech, and generate_music. The mention of image-to-video animation further sharpens the scope.

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 gives usable selection context (default Veo-3, alternates listed, optional start image), but never says when to prefer this over the generic sibling generate_with_poe_bot, nor any conditions to avoid this tool. Usage is implied rather than explicitly routed.

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 behavioral burden. It does disclose the side-effect profile at a high level ('optional local file attachments' sent, 'download whatever media it returns'), implying files are written locally. However it says nothing about authentication, rate limits, failure behavior for unknown bot names, or where/whether files are returned — significant gaps for a tool that performs network calls and disk writes.

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, zero filler, with the core action front-loaded and the routing guidance immediately after. Every clause earns its place.

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

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

For a 6-parameter tool with no output schema and no annotations, the description covers purpose, routing, and the general input/output shape (prompt + attachments in, media files out). It is largely complete, but given the absence of annotations it could say more about return values, file destinations, and failure modes.

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 83%, so the schema already documents model, output_dir, parameters, attachments, and prompt_flags in detail (including the poe.com/<bot>/api pointer). The description adds only a loose reference to 'optional local file attachments', which maps to the already-documented attachments param. 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?

States a specific verb+resource ('Call any Poe bot by name... then download whatever media it returns') and immediately carves out its niche relative to siblings by saying it is for bots 'the dedicated tools don't cover' and listing examples (upscalers, lip-sync, sound effects, background removal). An agent can distinguish this from generate_image/generate_video/generate_speech/generate_music without opening a schema.

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?

Gives explicit when-to-use and when-not-to-use guidance: use it for bot categories the dedicated tools do not cover, with concrete examples. The alternative (the dedicated sibling tools) is referenced as the comparison set, which is enough to route correctly.

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, so the safety profile is covered; the description correctly conveys a non-mutating enumeration. It adds the filtering semantics but says nothing about result size, pagination, or completeness of the returned model list, which matters for an enumeration 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?

A single sentence that front-loads the core action and appends the optional filter behavior with concrete examples. No wasted words 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 simple read-only list tool with one optional, fully documented parameter and no output schema, the definition covers what an agent needs to invoke it correctly. Only minor gaps (no mention of result volume or pagination) remain.

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 'search' parameter is already documented as a case-insensitive filter on name/description. The description supplements this with concrete example values ('veo', 'image', 'eleven'), which is genuinely useful, but adds no further syntax or constraint detail.

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?

Specific verb ('List') plus resource ('bot/model names available through the Poe API'), and the optional filtering behavior is stated up front. The resource is clearly distinct from the generation-oriented siblings (generate_image, generate_video, etc.), though the description never explicitly contrasts itself with them.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The phrase 'optionally filtered by a search term' implies how to narrow results, but there is no explicit statement of when to call this tool versus the sibling generation tools or when the search filter is warranted. Usage is inferable rather than spelled out.

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