partner_model_schema

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

There are no annotations, so the description must carry the full behavioral burden, and it does. It discloses that the tool makes no partner API call and spends nothing, that the data is PINNED from a vendored spec with a documented refresh mechanism, and that a miss should not be reported as nonexistent. It also describes the return envelope and caveats about enum granularity versus list_partner_models, which gives the agent accurate expectations about behavior.

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 front-loaded with the core purpose and then adds each necessary layer: wrapper command, side-effect-free guarantee, return structure, freshness behavior, and failure-handling guidance. Despite the length, every sentence earns its place, and there is no tautology or filler. The structure makes a complex tool easy to parse.

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 there is no output schema, no annotations, and zero schema description coverage, the description supplies all critical context: what the tool returns (including nested param fields), how to interpret 'binary' type, where the model values come from, how stale the data can be, how to refresh it, and how to handle a miss. An agent has everything needed to decide when to call it and how to interpret the result.

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 0%, so the description fully compensates. It defines the only parameter, 'model', as an alias from list_partner_models, which is essential operational knowledge: the agent must obtain the value from that sibling tool. It also clarifies that this alias identifies a partner model variant, so the parameter semantics go well beyond the bare schema type.

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 states a specific verb ('Show') and resource ('one partner model's callable parameters') and explicitly frames the output as 'the input to partner_generate'. It distinguishes this tool from partner_generate (which consumes the schema) and list_partner_models (which supplies the model alias), so an agent can immediately tell where it fits among 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?

The description clearly implies when to use this tool: to inspect the callable parameters for a model from list_partner_models before calling partner_generate. It also defines a boundary by stating 'Reads the spec only — no partner API call, no spend,' which tells the agent this is the safe, non-side-effect way to learn parameter structure. It does not explicitly say 'use this instead of partner_generate for schema introspection,' but the context is strong enough to route an agent correctly.

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