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

Annotations only say non-read-only and non-destructive. The description goes far beyond: it explains the human-in-the-loop process (a person generates and checks it), the async 202 response, that nothing is published on your behalf, that your score moves only when you commit the file, and the pricing/billing implications. This fully discloses the operational and financial behavior without 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 dense but every sentence adds value: purpose, artifact list, process, pricing, and a conditional alternative. It is front-loaded with the primary purpose ('REQUEST an artifact you are being marked down for not having') and then expands logically. It could be slightly more compact, but it is appropriately sized for the complexity.

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?

The tool has no output schema, so the description must explain the return behavior, which it does (202, async, human generation). It also covers billing, the score-commit relationship, and how to list available artifacts. The main omission is an explicit definition of `slug`, which is required and unexplained. Overall, it is largely complete but with one notable gap.

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 only 33% (only `context` has a description). The description explains the `artifact` enum values and the omit-to-list behavior, but `slug` (the only required parameter) is never described—neither in the schema nor the description. The agent is left to infer that slug identifies the live surface/API, which is a significant gap for a required parameter.

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 verb 'REQUEST' and the resource 'artifact', listing the specific artifact types (apis-json, agent-card, mcp, arazzo, rules, scopes, security) and the fallback behavior of omitting `artifact` to list what can be made. It distinguishes this tool from siblings like `submit_artifact` and `find_artifacts` by framing it as requesting a human-generated artifact for a missing item.

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 clear usage context: use when you are marked down for lacking an artifact, and it notes the async 202 return and that you must commit the file for your score to move. It also offers an alternative (`report_correction`) for incorrect data, but does not explicitly exclude other tools like `submit_artifact` or `find_artifacts`. The pricing and inclusion details further clarify when it applies.

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