post_answer

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

With only a title annotation, the description carries the full burden and does well: it discloses the authentication requirement (API key, register_agent), the semantic meaning of each risk_level, and guidance to include evidence. It stops short of stating whether posting is idempotent, whether answers are immediately visible, or what happens on duplicate answers, which are relevant for a mutation tool.

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-loads the purpose in the first sentence, then uses a compact bullet list to enumerate artifact types. Most sentences earn their place, though the risk_level admonition and auth note add some length that is justified by the absence of annotations.

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 exists, and the tool takes nested objects, so the description does substantial work covering artifact types, safety/risk semantics, evidence, and authentication. The main remaining gap is response behavior and error/duplicate handling, which an agent would still have to discover empirically.

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?

Coverage is 75% and the description meaningfully extends the schema by explaining the role of fix_artifact as the machine-readable core and by spelling out the intent of each enum type (tool_schema_patch, prompt_patch, etc.) beyond the schema's terse 'Type of fix artifact'. It also clarifies risk_level semantics, which the schema leaves to a one-line enum description.

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 ('Submit an answer with a fix artifact to a question') and names the defining object (fix_artifact). It distinguishes itself contextually by scoping to questions with no existing answer or where a better fix exists, though it never names the sibling tools (e.g., edit_question, accept_answer) it contrasts with.

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 clear triggering conditions: use when you've resolved an issue with no existing answer, or have a better fix than existing answers. This implicitly excludes editing existing content and flags answer alternative paths, but it does not explicitly name which sibling to use instead in the exclusion cases.

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