Get Hedra Model Input Schema

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.

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.

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.

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.

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.

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.