Codex Pets Registry

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

Annotations already declare the mutation/idempotent/open-world profile, but the description adds far more: server-paid generation with up to 13 provider calls, retry-with-delay semantics that can incur extra charges, 200 tasks/day global and 10/IP rate limits in Moscow time, admin allowance extensions, unlisted results expiring after 24 hours, and an experimental-quality caveat. This is exactly the cost and side-effect context an agent needs before a write with no undo.

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?

Front-loaded with purpose then usage, limits, return handling, exclusions and caveats, and each sentence carries operational weight. It is dense and runs long, but almost nothing is filler except the slightly redundant restatement of the retry cost in the final sentence.

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?

With no output schema and no annotations describing return behavior, the description supplies the return contract (task ID), the follow-up tool to poll, and result lifetime (24h, unlisted). Combined with the rate limits and failure semantics, it is complete enough to invoke and manage the call correctly.

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 must carry all three parameters. It handles requestId well (fresh random UUID, reuse unchanged on retry) and implies prompt via 'text brief', but displayName (max 80 chars) is never mentioned, leaving a required-adjacent field unexplained. Partial compensation only.

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 precise verb+resource (generate a new animated pet from a text brief) and explicitly separates itself from siblings with 'Do not use to publish a pet, edit an image, or create a manual administrator request.' An agent can distinguish it from get_pet_generation, get_pet, and search_pets without opening any schema.

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?

Gives an explicit trigger ('Use only when the user requests a new animated pet from a text brief'), names two sibling tools (get_pet_generation for polling, get_pet_request_info implied), and lists concrete exclusions. The when-to-use/when-not split is fully spelled out.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. Description adds that output includes Markdown, HTML, or SVG URL, which are behavioral details not covered by annotations. Could mention more about prerequisites or error handling, but sufficient given 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?

Two sentences, front-loaded with purpose, second sentence providing exclusions and alternatives. No wasted words.

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 simple one-parameter tool with no output schema, the description covers what it returns, constraints (approved pet slug), and when to avoid. Complete given the tool's simplicity and rich annotations.

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 100%, so the parameter 'slug' is fully documented. The description reinforces that it must be an exact slug of an approved pet but adds no new semantic detail beyond the 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 clearly states the tool's purpose: generating README badge Markdown, HTML, or SVG URL for a known approved pet slug. It distinguishes from siblings by explicitly naming alternatives for other use cases.

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?

Explicitly provides when to use (known approved pet slug, need badge code) and when not to use (animated cards, iframe embeds, install instructions, pet discovery), listing specific alternative tools.

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

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

Annotations already indicate safe, read-only, idempotent behavior. The description adds context that the input must be an 'approved' pet slug and that the output includes Markdown, HTML, or GIF URL, which is useful beyond 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?

Two concise sentences, front-loaded with the core purpose and conditional usage. No wasted words.

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 the simple tool (one parameter, rich annotations, no output schema), the description sufficiently covers input and output types. It could mention the exact format of the returned code but is complete enough for selection and invocation.

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 100% and the parameter 'slug' is well-described in the schema. The description reinforces the requirement ('known approved pet slug') but does not add significant new meaning beyond the 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 clearly states the tool's purpose: retrieving animated README card code (Markdown, HTML, or GIF URL) for a known approved pet slug. It distinguishes itself from siblings by listing specific alternative tools for other use cases.

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 guidance on when to use (for a known approved pet slug needing animated README card code) and when not to use (badges, embeds, install instructions, pet discovery), with named alternative tools.

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

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 mentions 'approved public Codex pet' which adds context about authorization, but does not disclose additional behavioral traits beyond the schema and 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?

Two sentences with no waste. The key information is front-loaded and every sentence earns its place, providing purpose and exclusions efficiently.

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 simple tool with one parameter, good annotations, and no output schema, the description covers when to use, what it returns, and what not to use it for. No gaps given the tool's complexity.

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 100% for the single required 'slug' parameter, which has a description. The description does not add extra semantic meaning beyond what the schema provides.

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?

Description clearly states the tool retrieves website embed HTML or URL for a known approved pet slug. It uses specific verbs ('get website iframe embed HTML or an embed URL') and distinguishes from sibling tools like get_badge_code.

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?

Explicitly states when to use (known approved pet slug, needs embed) and when not to use (README badges/cards, install instructions, pet discovery) with named alternative tools.

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

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

Annotations already indicate readOnlyHint, destructiveHint, and idempotentHint. The description adds useful context that it does not increment install/download counters, going beyond 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?

Two sentences, no redundant information, front-loaded with the primary purpose, and each sentence adds value.

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 simple tool with one parameter, good schema, and clear description that covers purpose, usage boundaries, and behavioral traits, it is fully complete.

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 100% with clear description of the 'slug' parameter. The description does not add new details about the parameter, so baseline score of 3 applies.

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 provides CLI or manual install instructions for a known approved pet slug, and distinguishes from sibling tools search_pets and get_pet by stating what it should not be used for.

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?

Explicitly states when to use (user wants install instructions for approved pet slug) and when not to use (search/inspect metadata), with named alternative tools (search_pets, get_pet).

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

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

Annotations already indicate readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds the return types (sanitized card, asset URLs, page URL, install command), providing useful behavioral context beyond 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?

Two sentences, front-loaded with purpose and usage condition. No wasted words; every sentence adds value.

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?

With one required parameter, rich annotations, and clear return behavior described, the description is fully 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.

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

Only one parameter (slug) with 100% schema coverage. Description confirms it expects an exact approved pet slug, adding no new syntax or constraints beyond the schema. 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 retrieves a specific pet's public card, assets, page URL, and install command using an exact approved slug. It distinguishes itself from sibling tools like search_pets by specifying the exact slug requirement.

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?

Explicitly says to use when you have an exact slug and need pet details; advises to use search_pets first for name/query or multiple results. Also warns against using for other specific get_* tools, providing clear alternatives.

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

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

Annotations only declare the safe-read profile; the description adds substantial behavior beyond that — this tool "never confirms, edits or starts a paid retry," failed results carry error.code/message/hint with automaticRetry=false, and unaccepted animationRevision gates ZIP download, metadata editing and gallery submission. That is exactly the operational context an agent needs before deciding its next call.

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?

Front-loaded with purpose and the read-only/never-mutates constraint, and nearly every sentence carries actionable state information. It is dense but slightly sprawling — the completed-result enumeration ("preview, name/description/tags" then "pet.json and spritesheet" then "other completed results include the ZIP") is fragmented and could be tightened.

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?

With no output schema and a single required param, the description fully covers return shapes across states: completed assets, metadata, ZIP, awaiting_confirmation jobs, and structured error fields. An agent can act on the response without any additional documentation.

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 must carry the parameter meaning; it only contributes that the generationId is "private" and scopes it to "your" task. It never mentions the 64-character hex format enforced by the pattern, nor what happens with an invalid or foreign ID, leaving a real gap.

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?

Opens with a specific verb+resource+key: "read your generation task by its private generationId." It is immediately distinguishable from siblings (generate_pet for new tasks, search_pets for listing, get_pet for the pet entity), so an agent can route correctly without opening any schema.

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?

Explicitly states when not to use it ("Do not use to list other tasks, publish results, or start another paid generation") and names the alternative (generate_pet for new user-requested tasks). It also supplies state-specific guidance: stop polling on failure, open the private preview for awaiting_confirmation jobs, and accept animationRevision before download/edit/submit.

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

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

Annotations already declare readOnly, idempotent, non-destructive, and not-open-world, so the safety profile is fully covered. The description adds useful context that this concerns the 'public' form and that manual request workflows are separate from automated generation, but it says nothing about the returned content, since there is no output schema.

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 sentences, all load-bearing: purpose, exclusion with named alternatives, and positive routing to sibling read tools. Front-loaded and waste-free.

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 zero-parameter, no-output-schema info tool, the description supplies enough to select and call it correctly, and annotations carry the safety profile. The only minor gap is that it does not enumerate the actual form fields or limit values, though that is reasonably left to the tool's response.

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 tool takes zero parameters (empty object schema, 100% coverage), so there is nothing for the description to disambiguate. Baseline 4 applies for a parameterless tool.

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 conveys the resource (pet request form fields and reference image limits) and its nature as a read-only info lookup, distinguishing it from generate_pet, get_pet_generation, search_pets, and get_pet. It is phrased obliquely through 'Use when the user wants...' rather than a direct declarative statement of what the tool returns, so it is clear but not maximally crisp.

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?

Explicit when-to-use ('request a new Codex pet or understand the public request form fields'), when-not-to-use ('Do not use to create, submit, update, or inspect private generation requests'), and named alternatives (generate_pet, get_pet_generation, search_pets, get_pet). Nothing about routing is left to inference.

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

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

Annotations already establish read-only, idempotent, non-destructive behavior. The description adds meaningful context beyond that by clarifying the search only covers approved public packs and explicitly excludes private generation requests, which is valuable behavioral scope not encoded in 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 compact and front-loaded with the core action, followed by precise routing instructions. Every sentence earns its place with no redundancy or filler.

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 search tool with fully documented optional parameters and clear sibling routing, the description covers what the tool returns, when to use it, and when to avoid it. The lack of an output schema is acceptable because the tool's purpose is to discover matching pet packs, which the description conveys.

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 100%, so all six parameters are already documented. The description restates the filter dimensions (query, kind, tags, author, compatibility) but does not add new semantic detail beyond what the schema provides.

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 uses a specific verb ('discover') with a clearly scoped resource ('approved public Codex pet packs') and enumerates the search dimensions. It explicitly contrasts itself with get_pet, making the tool's distinct role immediately clear.

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 gives explicit when-to-use guidance: prefer when no exact slug or when multiple candidates are needed. It also states what not to use it for and names the correct alternatives, get_pet_request_info and slug-specific get_* tools.

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