Server Quality Checklist

Tool Scores

• hedra_list_model_jobsA
  4.3/5.0
  Behavior4/5

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

  Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds valuable behavioral context: pagination (using cursor from previous response), ordering (most recent first), and the return shape ({jobs, next_cursor}). It does not mention potential errors or rate limits, but with strong annotations, 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.

  Conciseness5/5

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

  The description is compact and front-loaded with the core purpose. It uses a clear Args/Returns structure, includes optional/default/max constraints inline, and every sentence contributes necessary information without redundancy.

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

  Completeness5/5

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

  For a simple list operation with no output schema, the description covers all necessary context: purpose, pagination mechanics, argument descriptions, and the exact return structure. An agent can invoke and interpret the response correctly without external references.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters3/5

  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's parameter section largely mirrors the schema, only adding minor guidance on cursor usage ('pass the previous response's next_cursor'). It does not meaningfully enhance the schema's already thorough descriptions.

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

  Purpose5/5

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

  The description states a specific verb ('List') and resource ('jobs submitted to one specific model'), with clear scope ('one specific model') and ordering ('most recent first, paginated'). This distinguishes it from sibling tools like hedra_list_jobs, which likely lists jobs across all models.

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

  Usage Guidelines4/5

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

  The description clearly indicates this tool is for listing jobs for a specific model, which implicitly separates it from hedra_list_jobs. However, it does not explicitly state 'use hedra_list_jobs for all jobs' or provide when-not-to-use guidance, 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.

• hedra_get_jobA
  4.4/5.0
  Behavior4/5

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

  Annotations already declare readOnly/idempotent/non-destructive. Description adds meaningful behavioral context: return envelope structure, error format, and how asset_id can be reused as input to other models. No contradiction.

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

  Conciseness4/5

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

  Well-structured with clear sections: purpose, usage guidance, args, returns, error handling. All sentences are informative, though slightly verbose for the amount of unique content.

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

  Completeness5/5

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

  No output schema exists, so description correctly details the return JSON structure including outputs[].url and outputs[].asset_id, plus error handling. Covers both success and failure modes fully.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters3/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  Schema description covers 100% of parameter semantics (format and origin of job_id). Description reiterates this but doesn't add new syntax details, so baseline 3 is appropriate.

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

  Purpose5/5

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

  Description begins with 'Fetch the full result envelope for a job', clearly stating the verb and resource. It distinguishes itself from siblings by contrasting with hedra_get_job_status and hedra_wait_for_job.

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

  Usage Guidelines5/5

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

  Explicitly states when to use this tool vs alternatives: use hedra_get_job_status for lighter progress checks and hedra_wait_for_job to block. Also provides error handling guidance for job not found.

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

• hedra_get_modelA
  4.4/5.0
  Behavior4/5

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

  Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, covering the safety profile. The description adds valuable behavioral details beyond annotations: the exact error message format for NOT_FOUND, the return type (JSON object), and the limitation that this tool alone is not enough to construct a valid submit_job call. It does not contradict annotations, and it enriches the agent's understanding of edge cases.

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

  Conciseness4/5

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

  The description is well-structured with separate sections (main purpose, alternative guidance, Args, Returns, Error Handling) and is not overly verbose. Each sentence contributes meaningful information. A minor deduction for the redundant Args section that largely mirrors the schema, but overall it is efficient and front-loaded with the core purpose.

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

  Completeness5/5

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

  For a tool with one parameter, no output schema, and strong annotations, the description covers all essential contexts: what the tool returns (including specific fields), how to handle errors, and its relationship to sibling tools for job submission. The absence of an output schema is compensated by the field list and error format, making the description complete for an agent to invoke the tool correctly.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters3/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  Schema description coverage is 100% and already provides the required 'model_id' with examples and a note to get valid IDs from hedra_list_models. The description's Args section repeats this information without adding meaning beyond a single example. Since the schema carries the semantic load, the description adds minimal incremental value, meeting the baseline of 3.

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

  Purpose5/5

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

  The description clearly states the tool's purpose with a specific verb ('Get full catalog details for one Hedra model') and enumerates the exact fields returned (display name, modality, description, capability metadata). It explicitly distinguishes itself from the sibling hedra_get_model_input_schema, making the purpose clear in context.

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

  Usage Guidelines5/5

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

  The description gives explicit when-to-use guidance: it provides a human-readable overview, while instructing to use hedra_get_model_input_schema instead for exact machine-typed parameters needed to submit a job. It also directs users to hedra_list_models for valid IDs and mentions checking it on error. This is a model of clear alternative usage.

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

• hedra_get_model_input_schemaA
  4.4/5.0
  Behavior4/5

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

  Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, which establish safety. The description adds meaningful behavioral context beyond these: it explains the return structure (OpenAPI operation object with components.schemas.Input_<model>), notes that API validation is strict, and warns that guessing wastes a submit call. This adds real value while not 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.

  Conciseness4/5

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

  The description is well-structured with clear sections (core statement, usage warning, args, returns, examples) and is front-loaded with the exact purpose. It is a bit verbose, particularly in the return explanation and the repeated model_id example, but every section contributes useful information. Slight redundancy prevents a 5.

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

  Completeness5/5

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

  For a read-only schema-introspection tool, the description is completely self-contained. It explains the tool's context (input shapes vary by model), what the return object contains and where to find the relevant schema, and why this tool is necessary before submission. No output schema exists, but the description compensates fully by detailing the return structure. The complexity of the underlying operation is well addressed.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters3/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  The input schema already fully documents the single parameter model_id with type, minLength, and a description including examples and a reference to hedra_list_models. The main description repeats the parameter info almost verbatim, adding no new semantic detail. Since schema coverage is 100%, a baseline of 3 is appropriate.

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

  Purpose5/5

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

  The description clearly states the tool 'Get the exact, typed JSON Schema for one model's submit "input" object' with a specific verb and resource. It further details what the schema contains (required fields, enums, media references) and differentiates itself from siblings by explicitly positioning it as a prerequisite for hedra_submit_job.

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

  Usage Guidelines5/5

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

  The description provides explicit when-to-use guidance: 'ALWAYS call this before hedra_submit_job for a model you haven't used yet'. It also gives a concrete don't-use condition ('if you already fetched this model's schema earlier') and examples that contrast against the alternative of guessing. This is exemplary usage guidance.

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

• hedra_list_model_voicesA
  4.4/5.0
  Behavior4/5

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

  Annotations already declare read-only and idempotent behavior, so the description adds beyond that by detailing error handling ('Error [NOT_FOUND]...' when model has no voice input) and the scoping nuance (voices differ by provider). This provides useful behavioral context not present in annotations.

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

  Conciseness4/5

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

  The description is well-organized with clear sections for Args, Returns, and Error Handling. While slightly verbose for a simple one-param tool, every sentence adds information and the structure aids scanning.

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

  Completeness5/5

  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 one parameter, the description covers purpose, usage timing, parameter meaning, return format, and error behavior. No output schema exists, so the description appropriately explains the return shape, making it fully complete.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters4/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  Schema coverage is 100% for the single parameter, but the description adds meaningful examples ('hedra-avatar', 'elevenlabs-v3') and clarifies the parameter is the model's public id. This supplements the schema's examples, providing extra semantic value.

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

  Purpose5/5

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

  The description clearly states the tool lists text-to-speech voices for a specific model, using a specific verb and resource. It distinguishes itself from siblings like hedra_list_models (which lists models) and hedra_get_model (which retrieves model details), making its unique purpose unambiguous.

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

  Usage Guidelines4/5

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

  The description explicitly says 'Use this before submitting a job to a speech or avatar model that takes a voice_id input,' providing clear when-to-use guidance. It does not explicitly name alternatives or exclusions, but the context is sufficiently clear for selecting this tool.

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

• hedra_get_balanceA
  4.5/5.0
  Behavior4/5

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

  Annotations already convey read-only, idempotent, and non-destructive behavior. The description adds valuable context beyond annotations: the return shape (JSON {balance, currency}), the meaning of the balance (prepaid USD for API generations), and the distinction from Studio credits, all of which help the agent understand what to expect and how to interpret results.

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

  Conciseness5/5

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

  The description is well-structured and front-loaded: it states the core purpose, adds a critical distinction (separate from Studio credits), and provides concrete use cases and return format. Every sentence contributes meaning; no filler or repetition.

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

  Completeness5/5

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

  For a zero-parameter read-only balance lookup, the description fully covers what the tool does, what it returns, and when to use it. The explicit return format compensates for the lack of an output schema, making the tool's behavior predictable.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters4/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  The tool has zero parameters; the schema is an empty object. A baseline of 4 is appropriate because there is no parameter semantics for the description to add.

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

  Purpose5/5

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

  The description explicitly states 'Get the current spendable balance of the Hedra API wallet' with a specific verb and resource, and distinguishes this from Hedra Studio credits. This eliminates any ambiguity with sibling tools like hedra_estimate_cost or hedra_get_usage.

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

  Usage Guidelines4/5

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

  Provides clear 'Use when' examples: checking balance before bulk jobs and when a hedra_submit_job fails with INSUFFICIENT_BALANCE. It also clarifies the separation from Studio credits, which helps with tool selection, though it does not explicitly name alternative tools for non-balance queries.

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

• hedra_list_jobsA
  4.5/5.0
  Behavior4/5

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

  Annotations already declare readOnly/openWorld/idempotent/non-destructive, and the description adds valuable behavioral context: pagination with a cursor (next_cursor), the has_more inference, and ordering across all models. It does not describe error handling or rate limits, but for a read-only list operation it covers the key dynamic behavior well.

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

  Conciseness5/5

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

  The description is well-structured with clear sections (Args, Returns, Examples) and every sentence adds value. It avoids fluff and uses concise, actionable language.

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

  Completeness5/5

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

  There is no output schema, but the description explicitly states the return JSON structure and how to infer has_more. It also covers pagination behavior and provides usage examples, making it complete for a list operation. The sibling differentiation adds to contextual completeness.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters3/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  Schema description coverage is 100% and the description essentially restates the same parameter details (limit default/max, cursor usage). It does add a small note about interpreting next_cursor for pagination, but overall it does not go substantially beyond what the schema already provides, so the baseline score of 3 is appropriate.

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

  Purpose5/5

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

  States the specific action (list jobs) with clear scope (across all models, submitted with this API key) and ordering (most recent activity first). It explicitly distinguishes itself from the sibling tool hedra_list_model_jobs by noting the all-models scope, so the purpose is unambiguous.

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

  Usage Guidelines5/5

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

  Provides explicit 'Use when' and 'Don't use when' guidance, naming the alternative tool hedra_list_model_jobs and explaining when it is more appropriate. This gives the agent clear decision criteria for tool selection.

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

• hedra_estimate_costA
  4.6/5.0
  Behavior4/5

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

  Annotations declare readOnlyHint=true and destructiveHint=false, and the description reinforces safety with 'WITHOUT submitting a job or spending any wallet balance.' It adds valuable nuance about non-quotable models (server-side measurement, refusal fallback), which goes beyond the annotations. No contradiction; slight room for more detail on idempotency but not significant.

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

  Conciseness4/5

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

  The description is well-structured with clear sections (intro, args, returns, examples) and no filler. It is slightly long due to duplicate parameter listing, but each section adds value and the examples are practical. The front-loaded first sentence captures the core purpose.

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

  Completeness5/5

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

  For a two-parameter tool without an output schema, the description covers the key aspects: purpose, safety, parameter construction, return variability, and edge cases like non-quotable prices. It references sibling tools for building inputs and is robust enough for an agent to invoke correctly.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters4/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  Schema coverage is 100%, so baseline is 3. The description adds meaningful cross-tool guidance: the input object is 'the same input object you'd pass to hedra_submit_job' and should be 'built against hedra_get_model_input_schema.' This provides context not present in the schema, earning a 4.

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

  Purpose5/5

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

  The description opens with 'Estimate the cost in USD of running a model with a given input, WITHOUT submitting a job or spending any wallet balance,' using a specific verb and resource and explicitly distinguishing it from job submission. This clearly separates it from sibling tools like hedra_submit_job.

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

  Usage Guidelines5/5

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

  The description explicitly recommends using it before hedra_submit_job for expensive operations and provides concrete use/don't-use examples ('Use when: about to generate a 4K video... Don't use when: the model is cheap/fixed-price'). This names the alternative and gives clear criteria.

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

• hedra_get_usageA
  4.6/5.0
  Behavior4/5

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

  Annotations already cover read-only and idempotent behavior. The description adds a valuable behavioral warning that the return shape depends on Hedra's current report format, alerting the agent not to assume a fixed schema. This goes beyond annotations and is useful for handling the response.

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

  Conciseness5/5

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

  The description is compact and front-loaded with the core action, followed by a return note and practical examples. Every sentence earns its place without redundancy.

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

  Completeness4/5

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

  For a zero-parameter read tool with strong annotations, the description covers purpose, output variability, and selection guidance. It compensates for the missing output schema by warning about format instability. A minor gap is not enumerating the breakdown fields, 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.

  Parameters4/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  The tool has zero parameters, so schema coverage is trivially 100% and the baseline for 0 parameters is 4. The description does not need to explain parameters; it instead provides output context, which is appropriate.

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

  Purpose5/5

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

  The description clearly states it retrieves 'API wallet usage/spend history and breakdown,' which is specific and distinguishes it from hedra_get_balance (current balance) and hedra_estimate_cost (cost estimation). The use-case example further reinforces the purpose.

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

  Usage Guidelines5/5

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

  Explicitly provides a 'use when' example (monthly spend query) and a 'don't use when' case (current balance) with a named alternative (hedra_get_balance), making selection criteria unambiguous.

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

• hedra_get_job_statusA
  4.7/5.0
  Behavior5/5

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

  Although annotations already declare readOnlyHint and idempotentHint, the description adds substantial behavioral context: it is 'cheaper' for repeated polling, it only returns status/progress (not full outputs), and it instructs users to transition to hedra_get_job once terminal statuses are reached. It also discloses the return format and valid status values, which is beyond the annotations and truly enhances understanding.

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

  Conciseness5/5

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

  The description is well-structured with sections for Args, Returns, and Examples, front-loading the core purpose. Every sentence contributes value: cost comparison, usage guidance, and terminal-state transition. Despite covering multiple aspects, it remains tight and readable without redundancy.

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

  Completeness5/5

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

  The tool is simple (one param, no output schema), but the description compensates for the missing output schema by explicitly listing the return fields and statuses. It covers cost, when to use, when not to use, and what to do after completion. It is fully self-contained for an agent to invoke correctly without external context.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters3/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  The schema already covers the single parameter job_id with a description providing format and source ('job_<uuid> — returned by hedra_submit_job'). The description repeats 'the job id from hedra_submit_job', adding no new semantic nuance. With 100% schema coverage, the baseline of 3 is appropriate; there is no additional meaning to extract.

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

  Purpose5/5

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

  The description opens with 'Lightweight poll of a job's current status and progress', clearly identifying the specific verb (poll) and resource (job status). It explicitly distinguishes itself from hedra_get_job ('cheaper than hedra_get_job') and implies a lighter operation, differentiating from the sibling that retrieves full results. This is a specific and unambiguous purpose statement.

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

  Usage Guidelines5/5

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

  The description provides explicit usage instructions: 'Use when: manually polling a long-running job in a loop with your own delay' and 'Don't use when: you just want to wait for completion and get the result in one call (use hedra_wait_for_job instead)'. It also mentions timing relative to job completion ('Once status is COMPLETED or FAILED, call hedra_get_job'). This leaves no doubt about when to select this tool over alternatives.

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

• hedra_list_modelsA
  4.7/5.0
  Behavior4/5

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

  Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds useful behavioral context: filtering by modality, the return format (a 'models' array with id/name/modality), and that omitting the parameter lists all. This goes beyond annotations, though it doesn't mention pagination or rate limits—minor gap for a list tool.

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

  Conciseness5/5

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

  The description is well-structured into Args, Returns, and Examples sections. It front-loads the core purpose in the first sentence and every subsequent line adds practical value—examples, alternative references, and conditional usage. No fluff.

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

  Completeness5/5

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

  For a simple list tool with one optional parameter and no output schema, the description covers everything: purpose, use cases, parameter semantics, return shape, and alternatives. It is fully self-sufficient for an agent to select and invoke the tool correctly.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters4/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  Schema coverage is 100%, so baseline is 3. The description adds example usage ('What video models can I use?' -> modality="VIDEO") and clarifies the default behavior ('Omit to list all'), which the schema does not explicitly state. This adds real value beyond the structured field.

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

  Purpose5/5

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

  The description clearly states the tool lists all AI models across image, video, and audio/avatar categories, naming specific partners. It distinguishes itself from siblings by explicitly mentioning alternatives like hedra_get_model_input_schema and hedra_submit_job, and provides a 'Don't use when' case.

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

  Usage Guidelines5/5

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

  The description gives explicit guidance: use this first to discover a model's public id before calling other tools, includes concrete 'Use when' examples (e.g., 'What video models can I use?') and a clear 'Don't use when' with the alternative tool named. This is textbook usage differentiation.

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

• hedra_submit_jobA
  4.9/5.0
  Behavior5/5

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

  Beyond annotations (which only say non-readonly, non-idempotent), the description discloses async submission with immediate job return, billing impact, idempotency key replay behavior, strict validation, and detailed error handling. No contradiction.

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

  Conciseness5/5

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

  Though lengthy, the description is well-structured with front-loaded warning on billing, followed by async behavior, prerequisites, parameter details, return format, and error handling. Every section serves a purpose; nothing is redundant.

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

  Completeness5/5

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

  For a complex tool with nested input and asynchronous behavior, the description covers prerequisites, return format, error handling, and follow-up steps. It even explains media upload and asset reuse, leaving no significant gap for an agent to invoke correctly.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters4/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  Schema coverage is 100%, so baseline is 3. The description adds meaningful semantics: explains media reference format (source/url/asset_id), idempotency key purpose, and model_id source. This goes beyond the schema's simple descriptions, but does not cover every edge case.

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

  Purpose5/5

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

  The description opens with 'Submit a generation job to a Hedra model', clearly stating the verb and resource. It distinguishes itself from sibling tools by emphasizing this starts real billed work and returns a job_id, unlike list/status tools.

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

  Usage Guidelines5/5

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

  Provides explicit when-to-use guidance: call hedra_estimate_cost first for expensive requests, confirm with the person, fetch the model input schema before first use, and follow up with hedra_wait_for_job or status polling. It names direct alternatives and gives operational workflow.

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

• hedra_upload_fileA
  5/5.0
  Behavior5/5

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

  Goes well beyond annotations by disclosing the 1-hour URL expiry, the fact that moderation failures happen later at submit time, and specific error message formats. It adds meaningful context about what the tool does and does not do at upload time.

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

  Conciseness5/5

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

  The description is thorough but well-structured with clear sections for usage, examples, and error handling. Every sentence provides actionable information without fluff, and the length is justified by the complexity of the tool.

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

  Completeness5/5

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

  Despite lacking an output schema, the description documents the exact return JSON shape ({url, content_type, expires_at}) and how to pass it to model inputs. Combined with examples and error handling, the description fully equips an agent to use the tool correctly.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters5/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  Even though the schema already describes all parameters, the description adds crucial semantics: exactly one source must be provided, file_path must be readable on the MCP server, source_url must be https and fetched/re-uploaded, and base64_data requires filename. This clarifies relationships and constraints not obvious from the schema alone.

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

  Purpose5/5

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

  The description clearly states the tool uploads a file (image, video, or audio) to Hedra and returns a presigned URL for use in hedra_submit_job. It distinguishes itself from siblings by explicitly contrasting with reuse of existing assets and specifying its role as a prerequisite for media submissions.

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

  Usage Guidelines5/5

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

  Provides explicit when-to-use examples (image-to-video start frame, voice cloning sample) and a clear when-not-to-use case with an alternative (passing asset_id directly to hedra_submit_job). Also states the free-tier behavior, which helps decide when this step is necessary.

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

• hedra_wait_for_jobA
  5/5.0
  Behavior5/5

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

  Annotations provide readOnly/idempotent hints, but the description adds valuable behavioral context: timeout behavior, last-known status semantics, the timed_out flag, and guidance to call hedra_get_job again if timeout occurs. 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.

  Conciseness5/5

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

  Well-structured with Args, Returns, and Examples sections. Each sentence serves a purpose—no filler—and the format makes it easy to scan. Despite the length, it remains concise and front-loaded.

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

  Completeness5/5

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

  Completely covers the tool's purpose, parameters, return shape (including timeout edge case), and usage patterns. With no output schema, the description successfully carries the burden of explaining expected responses.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters5/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  Schema covers 100% of parameters, but the description enriches each: job_id source from submit, timeout_ms default/max and what happens on timeout, poll_interval_ms as delay between checks. This adds meaning beyond the raw schema definitions.

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

  Purpose5/5

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

  The description clearly states it polls a job until COMPLETED or FAILED (or timeout) and returns the full result in one call. This specific verb+resource+scope distinguishes it from sibling tools like hedra_get_job and hedra_get_job_status, which are single-poll lookups.

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

  Usage Guidelines5/5

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

  Includes explicit 'Use when' and 'Don't use when' examples, naming hedra_get_job_status as the alternative for parallel polling and noting there is no multi-job wait tool by design. This is clear, actionable guidance for tool selection.

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