list_models

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It discloses the user-scoped nature of the list, the status/type fields returned, the include_unsaved behavior, and pagination semantics with default/max limits. It does not mention ordering or error behavior, but it provides substantially more behavioral transparency than a minimal description would.

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 and efficient: the purpose is front-loaded, the return fields are summarized in one sentence, a critical cross-tool note is set apart, and the Args block is compact and readable. Every sentence adds useful information, and there is no filler or tautology.

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?

This is a simple list operation with three optional parameters and no output schema. The description covers what the tool does, what it returns, how to page, how to include unsaved models, and how the returned model_hash connects to all other model endpoints. Nothing essential for correct selection or invocation 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?

The input schema provides only titles and defaults, with 0% description coverage. The description compensates fully by explaining each parameter: include_unsaved includes draft/unsaved models, limit is the maximum number with a default of 50 and max of 500, and offset is the number to skip for paging. This is exactly the meaning an agent needs beyond the bare 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?

The description opens with a specific verb and resource: 'List all Marketing Mix Models for the authenticated user.' It goes on to enumerate the returned fields, making the tool's role clear and distinguishing it from narrower siblings like get_model or get_model_status. The scope is explicit, and the distinction between listing all models versus retrieving a specific one is unambiguous.

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 clear context for when to use the tool by explaining that all other model endpoints require a model_hash and that list_models is the source of that hash: 'Use the model_hash from this response.' It does not explicitly name alternatives or exclusions, such as 'use get_model for a single model,' but the guidance is strong enough for an agent to infer the appropriate use case.

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