List available custom models

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

Annotations already declare readOnly/idempotent/openWorld/non-destructive, so the safety profile is covered. The description adds genuinely new behavior: the optional token changes the result scope (user-specific vs project-wide) and the call returns a single page requiring start/limit iteration — neither is derivable 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?

Three short sentences, zero filler, with the core purpose front-loaded and pagination guidance last. It is tight, though the auth note could be a touch more explicit about what happens without the token.

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?

No output schema, and the page-return note covers the return shape minimally. For a 4-parameter filter tool with 0% schema coverage, the description omits sortBy and publishedState entirely, which are the main levers an agent would need to use.

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 0% across 4 parameters, so the description must carry the burden. It covers start and limit for pagination but says nothing about sortBy (6 enum values) or publishedState (8 enum values), leaving half the parameters' semantics to inference from enum names 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?

States a specific verb and resource ('Read custom models available to the Adobe project') with a clear scope qualifier. It is readily distinguishable from the generation-oriented siblings, though the description never explicitly contrasts itself with them.

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 operational guidance: FIREFLY_USER_TOKEN is optional for user-specific access, and 'use start and limit to continue' for pagination. However, it never states when to call this versus alternatives (e.g., verify_credentials, get_job_status) or any preconditions.

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