APIXO

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

Annotations already declare destructive=true, readOnly=false, and idempotent=false. The description adds useful context that the call is billable, backend validation is authoritative, and rejected or unconfirmed submissions must not be automatically resubmitted, but it does not say what is destroyed or what permissions and audio inputs cloning requires.

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 long generic boilerplate that spends most of its length on identifier redaction and reply presentation, which do not help tool selection or invocation. The actual purpose is not front-loaded, and the text is not tailored to clone_voice.

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 seven-parameter nested creation tool with an output schema, the description should at minimum state that it clones a voice from reference audio and differentiate it from design_voice. It does neither, so despite covering generic workflow rules, it is incomplete for this specific 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 the schema already documents all seven parameters, including file_bindings, session_title, session_id, and base_run_id semantics. The description restates routing constraints such as 'no mode, model fields, defaults or voice choices are inferred' but adds little parameter meaning beyond the schema, making the baseline 3 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 never names voice cloning, reference audio, or a target speaker; the opening line, 'Create one independent billable Studio task,' is generic to every creation sibling. The only voice-related hint is 'voice choices' in a sentence about non-inference, which does not tell an agent that this tool clones a voice from a sample.

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 generic workflow instructions (read list_models.defaults, then get_model_schema, use session_title/session_id/base_run_id) but never says when to choose clone_voice over design_voice or generate_speech. The only sibling it names is generate_task, and only to note that model is required.

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, the description discloses important behavior: tasks are billable, backend validation is authoritative, rejected or unconfirmed submissions must not be auto-resubmitted, and returned identifiers must be preserved for later workflow steps. It also clarifies that omitting technical identifiers applies only to user-facing replies and not to tool results. This adds meaningful operational context without contradicting 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 long block of generic creation-tool boilerplate that repeats policy-level instructions likely shared across many siblings. It buries the few design_voice-specific details inside verbose guidance and is not front-loaded around what the tool actually does or when to use it.

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 complex nested schema, rich annotations, and an output schema, the description covers operational mechanics reasonably well: defaults lookup, schema lookup, file bindings, session/version handling, and identifier preservation. What it does not provide is domain context for voice design itself, such as what inputs produce which kind of voice output or why an agent would choose this tool over clone_voice or generate_speech.

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 parameter definitions already carry much of the load. The description still adds useful cross-parameter meaning: model can be omitted to use the default, explicit model selects a public task model, session_title starts a new topic, session_id continues one, and session_id plus base_run_id versions an existing run. It also warns that flat model parameters and legacy reference_images/reference_audio are not accepted, which is not obvious from the schema alone.

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 says it creates one independent billable Studio task, which is a concrete operation, but it never states that this tool designs a voice or what kind of voice-design task it performs. It also does not distinguish design_voice from siblings like clone_voice or generate_speech, leaving the agent to infer the actual purpose from the name alone.

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 procedural guidance for model defaults, schema lookup, session_title vs. session_id, and base_run_id versioning. However, it never says when to use design_voice instead of another sibling creation tool, so tool selection remains implicit rather than explicitly guided.

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 mutation, non-idempotence, and destructuring, but the description adds substantive context beyond them: the task is billable, backend validation is authoritative, no modes/models/voice choices are inferred or injected, legacy reference_images/reference_audio and flat model parameters are rejected, and the agent must never auto-resubmit after a rejection or unconfirmed submission. These are genuine operational constraints an agent would not derive from 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 operative calling instructions are reasonably front-loaded in the first several sentences, but the latter half drifts into reply-presentation policy about hiding task_id, session_id, run_id, voice_id, and file IDs — useful context, yet verbose and loosely tied to invoking this specific tool. There is noticeable repetition around identifier retention.

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?

An output schema exists, so return-value documentation is not required, and the routing/identifier lifecycle is well covered. What is missing is the most basic thing an agent needs for this specific tool: that it produces images, and any hint about image-specific input expectations, cost per generation, or typical latency — so the description is complete on workflow mechanics but silent on tool-specific substance.

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 few things the schema does not spell out as directly — that input must carry original model parameters with explicit file_bindings, that reference_files and direct URLs must not be mixed, and that legacy reference_images/reference_audio are not accepted — but the session_title/session_id/base_run_id semantics largely restate the parameter 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 opens with "Create one independent billable Studio task," which states a verb and a resource but never says what is actually generated (an image). It reads as generic boilerplate shared with generate_task, generate_video, generate_music, and generate_speech, so an agent has no textual basis for distinguishing this tool from its siblings beyond the tool name itself.

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 real workflow guidance: read list_models.defaults for the default model, read get_model_schema for the full schema, use session_title for a new topic, session_id to continue, and session_id plus base_run_id for a version. However, it never states when to choose generate_image over generate_video or generate_task, and offers no exclusions, so routing between creation siblings is left implicit.

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

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

Annotations already declare non-read-only, non-idempotent, destructive creation; the description adds the important trait that each call is billable and that 'Backend validation is authoritative' with no inferred mode/model/default/voice injection. It also discloses rejection/retry behavior. It stops short of saying what a failed or partial submission leaves behind, but the added cost and validation context is substantive beyond 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 core instruction is front-loaded, but a large share of the text is reply-formatting policy about redacting task_id/session_id/user IDs, which does not help an agent decide or invoke this tool. Sentences are run together in a dense block, forcing the reader to sift operational rules from presentation rules.

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 nested, 7-parameter creation tool with annotations and an output schema, the definition covers model selection, schema discovery, attachment binding, session continuation, versioning and resubmission policy. An agent can invoke it correctly without additional external documentation.

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 baseline is 3, and the description genuinely adds semantics: input carries original model parameters and must follow get_model_schema, flat parameters and legacy reference_images/reference_audio are rejected, file_bindings must use fields from schema.mcp.attachments with zero-based indices, and session_title is ignored when session_id is supplied. It reinforces rather than merely restates 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?

Opens with a concrete verb and resource: 'Create one independent billable Studio task', and clarifies the routing to list_models.defaults and get_model_schema. It distinguishes shortcuts from generate_task ('generate_task requires model; shortcuts may omit it') but never states that the task is a music generation task nor contrasts itself with generate_image/generate_video/generate_speech, so the domain comes only from the tool name.

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 selection rules for the session family: session_title for a new topic, session_id to continue, session_id plus base_run_id for a version, and omit base_run_id for an independent work. It also sets prerequisites (read list_models.defaults, then get_model_schema) and a hard 'never automatically resubmit after rejection' rule. Missing is any guidance on when to pick this tool over the other generation 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?

Goes beyond the annotations meaningfully: it flags the task as "billable," states that backend validation is authoritative, warns that no mode/model/defaults/voice choices are inferred or injected, and instructs never to auto-resubmit or change model/session after a rejection. Those are real behavioral constraints an agent could otherwise violate. It omits runtime traits like latency or whether the returned task is synchronous vs. polled.

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 speech-specific content is buried after generic boilerplate, and the identifier-handling guidance is repeated three times in slightly different words (preserve the identifiers / retain the exact identifiers / show only when asked). The opening sentence is not front-loaded with the tool's actual purpose, so an agent must read the whole block to learn anything about speech generation.

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?

With an output schema, full annotation coverage, and 100% parameter descriptions, the structural burden is low, and deferring detailed params to get_model_schema is a reasonable design. But nothing describes what a successful speech result contains or the workflow for retrieving it (get_generation is a sibling that is never referenced), leaving the end-to-end flow under-explained.

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 constraints not captured in the schema: flat model parameters and legacy reference_images/reference_audio are rejected, and modes must be set explicitly rather than defaulted. It also clarifies the session_title vs session_id vs base_run_id relationship. The actual model-passthrough fields are deferred entirely to get_model_schema, leaving the input surface opaque here.

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 "Create one independent billable Studio task," a generic creation statement that never says this tool synthesizes speech/audio. Sibling tools (generate_image, generate_music, generate_video, generate_task) share the same boilerplate, so nothing here distinguishes the resource this tool actually produces beyond the tool name itself. Only a passing mention of "voice choices" hints at the domain.

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 concrete procedural context: read list_models.defaults for the default model, then get_model_schema for the full schema, and notes that generate_task requires model while shortcuts may omit it. It also distinguishes session workflows (session_title for a new topic, session_id to continue, session_id + base_run_id for a version). It does not, however, tell the agent when to pick this over generate_music/generate_video/generate_task for a speech-shaped request.

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, it discloses that the task is billable, that backend validation is authoritative, that no mode/model/defaults/voice are inferred, that legacy fields are rejected, and that identifiers must be preserved but omitted from user-facing replies. This adds substantial behavioral context for a mutating, non-idempotent creation tool.

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

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

The core purpose is front-loaded, but the description is dense and repetitive, especially around preserving versus omitting identifiers. The reply-presentation guidance could be tightened without losing meaning.

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 a 7-parameter nested creation tool with an output schema, the description covers the necessary workflow, validation expectations, session/version semantics, file binding rules, and identifier handling. No return-value explanation is needed because 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?

It adds meaningful semantics beyond the 86%-covered schema: model is required and selects the public task model, input must follow get_model_schema, no mode or fields are inferred, flat legacy parameters are rejected, and session_title/session_id/base_run_id have distinct workflows. It also explains file_bindings and reference_files usage constraints.

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 action and scope: 'Create one independent billable Studio task.' It distinguishes itself from shortcut creation tools by noting that generate_task requires a model while shortcuts may omit it, though it does not explicitly name those alternatives.

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 detailed workflow guidance: read list_models.defaults, use get_model_schema, set session_title for a new topic, session_id to continue, and session_id plus base_run_id for a version. It also warns not to resubmit after rejection. It lacks an explicit 'use this instead of X when Y' routing statement for 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?

Beyond the annotations, the description discloses billable task creation, authoritative backend validation, no automatic inference of mode/model/voice defaults, and a strong rule against resubmitting or changing model/session after rejection. It also explains which identifiers must be preserved. The only gap is that it does not further explain the destructive/billable consequences signaled by destructiveHint=true.

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 long and front-loads generic creation-tool language rather than video-specific purpose. It repeats identifier-handling guidance in two places ("Preserve returned..." and "Retain the exact returned identifiers...") and includes substantial user-facing reply-presentation instructions that do not directly help invoke the tool.

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 complex 7-parameter creation tool with an output schema and full schema description coverage, the definition covers the key workflow: model/default lookup, session continuation, versioning, file binding, validation authority, rejection behavior, and identifier retention. It lacks video-specific context and sibling-tool routing, but the workflow mechanics are otherwise well covered.

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 already 100%, but the description adds meaningful semantics: model can be omitted to use list_models.defaults, session_title is for new topics and ignored with session_id, base_run_id revises an existing run, file_bindings use declared attachment paths, and flat legacy parameters are rejected. This goes beyond the schema text and clarifies how parameters interact.

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 and resource ("Create one independent billable Studio task"), but it never states that this tool generates video and does not distinguish it from sibling creation tools such as generate_image, generate_music, or generate_task. An agent can tell it is a creation workflow, but not clearly why it should choose this tool over the other generate_* 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?

It gives explicit guidance for session_title, session_id, and session_id plus base_run_id, and points to list_models and get_model_schema for model/default/schema discovery. However, it does not say when to use generate_video versus generate_image, generate_music, generate_speech, or generate_task, so the core tool-selection guidance is implied rather than stated.

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

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

Annotations already declare the read-only, non-destructive, closed-world profile, so the description doesn't need to establish safety. It adds genuine context: a connected identity may query another account's task, retries should be finite, and missing session/run references, progress, and completion times are not inferred. Some of the text (identifier redaction rules) is reply-formatting policy rather than tool behavior, which weakens focus without causing contradiction.

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 purpose is front-loaded, but the text runs long and mixes tool semantics with response-formatting policy that belongs in a system prompt. Several sentences restate the same redaction rule three different ways. An agent must read past multiple clauses to reach parameter-related 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?

An output schema exists, so return values legitimately need no explanation, and the description does cover error handling, retries, identity scope, and media_type inheritance. What's missing is whether model must match the model used at creation and whether the call returns one task or a collection. The presence of extensive formatting guidance adds length but not invocation clarity.

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%, with task_id and media_type documented in the schema itself. The description reinforces task_id's scope ('public APiXO ID', cross-account query) and media_type inheritance ('automatically carry speech/voice media_type from creation', 'never infer it from task IDs or URLs'), which is useful. The model parameter remains essentially undefined beyond the pattern and becomes the main gap.

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

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

It opens with a specific verb-and-resource pair — 'Get task status and results using the supplied model and task_id' — which is unambiguous. It never names a sibling tool (get_model_schema, generate_task) or states which one retrieves what, so the agent has to infer the split. The remaining ~85% of the text addresses other concerns and dilutes separation from siblings.

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?

'Read-only queries may retry finitely' and 'missing tasks, unavailable models, or query errors must not trigger model switching or generation resubmission' are implicit guidance about which tools NOT to call after a failed lookup. There is no explicit statement of when to choose get_generation over generate_task/get_model_schema. Usage context is present but must be assembled from scattered negative constraints.

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 read-only/idempotent annotations, it discloses substantial context: that the schema is returned unfiltered, that APiXO uses custom request_schema.input.properties arrays rather than JSON Schema, that the backend validates parameters, that 'execution' does not convey permissions, that codecs come from schema.mcp, and that it is free with no account. These are non-obvious traits the agent could not otherwise know.

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?

Front-loaded with the core action and the key caveat about custom schema structure. The later sentences ('execution only describes transport/result adaptation...') are dense and slightly cryptic but each carries a distinct constraint, so waste is limited.

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?

An output schema exists, so return values needn't be spelled out, yet the description still characterizes the 'schema' field and warns about codec/decoder requirements — useful. For a one-param read tool this is nearly complete; only an explicit pointer to when to use it alongside list_models 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% and the single 'model' parameter already documents 'Canonical public model ID or exact slug alias; never a URL.' The description's 'by canonical ID or exact slug' restates that, adding no format or constraint detail beyond the schema. 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?

States a specific verb and resource — 'Read the complete published task model schema by canonical ID or exact slug' — with a clear scope ('complete published', 'without filtering or normalization'). It does not name the sibling it complements (e.g. list_models), so differentiation is inferred rather than explicit.

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 implies usage through 'Follow schema for model parameters; the backend validates them' and warns against inferring permissions from 'execution', but there is no explicit statement of when to call this versus list_models or the generate_* tools. The agent must infer that this is the step before generation.

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 cover readOnly/openWorld/destructive, so the bar is lower; the description adds real context by disclosing that the result is scoped to the OAuth session and that redaction is display-only — "tool result fields remain available for the workflow." That is a non-obvious behavioral guarantee the agent would otherwise have to infer, though no return-field inventory is given (the output schema covers that).

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 purpose is front-loaded in sentence one, but roughly 80% of the text is reply-formatting policy (omit IDs, never redact, show only when asked, show only what's needed) that repeats itself across several sentences. It is on-topic but bloated for a zero-parameter read.

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?

With zero parameters, a 100%-covered schema, an output schema, and safety annotations, the remaining gap is small; the description supplies the session scoping and the display policy an agent would otherwise get wrong. It is complete enough to invoke correctly without further documentation.

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?

This tool takes zero parameters, so the baseline of 4 applies; there are no arguments whose semantics need explaining. The description correctly indicates nothing is needed beyond the ambient OAuth session context.

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 first sentence gives a specific verb and resource: 'Return the APIXO profile connected to this OAuth session.' The scope (OAuth session, not an arbitrary user lookup) distinguishes it from the generation-focused siblings, though the description never names or contrasts any sibling explicitly.

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?

Guidance is given for presentation choices ("include its email only when relevant", "Show an identifier only when the user explicitly asks"), but nothing says when to call this tool — e.g., at session start to learn the connected account. Usage is implied rather than stated, and no alternatives or exclusions are named.

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 cover the read-only/idempotent/non-destructive profile, and the description adds genuine behavioral context beyond them: LLM gateways are excluded, no model defaults are built in, eligibility is not proof of working generation, discovery is free, and unavailable upstream returns an error. Useful caveats that would otherwise surprise an agent.

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 core purpose is front-loaded in sentence one, which is good. The following sentences are telegraphic fragments whose referents are unclear ('Candidate eligibility does not prove successful real generation'), costing more parsing effort than the words save.

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?

An output schema exists, so return values need no explanation, and the description covers the important ambient facts: exclusions, no built-in defaults, deferred loading, error behavior. Slightly short of complete because it never routes the agent to get_model_schema for the detail it says loads on lookup.

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 both enum parameters are documented in-schema, so the baseline is 3. The description mentions attachment_fields/result_codec but adds nothing about category or media_type semantics, so it does not exceed the schema's own 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?

States a specific verb and resource: reads the public task_api index and its default tool-to-model bindings. This is distinguishable from get_model_schema (schema lookup) and the generate_* siblings, though the description never names the sibling that returns detail so the split is only implied.

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 this is discovery-only ('candidate eligibility does not prove successful real generation') and hints that detail lives elsewhere ('modes and attachment_fields/result_codec load on schema lookup'), but never explicitly says to call get_model_schema for full detail. No explicit when-not or prerequisite statements.

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