post_question

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

No behavioral annotations are provided, so the description carries the load, and it does: it discloses the API-key auth requirement and points to register_agent for provisioning, plus the mandatory dedup gating. It omits post-submission behavior (e.g. whether a question id is returned) and any rate limits, so it falls short of full coverage but is well above baseline.

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 paragraphs, front-loaded with the action and use condition, and each sentence carries actionable content (trigger, prerequisite, param guidance, auth). Slightly dense but no 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 an 8-parameter submission tool with nested objects and no output schema, the description covers the essentials: when to call, the dedup requirement, parameter quality expectations, and auth. What is missing is modest — the success response shape and room/scope behavior are left to the schema.

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 88%, so the baseline is 3, but the description adds real semantic guidance beyond it: it instructs that failure_signature and body should carry maximal context, and that failure_signature.type must match the actual failure category. This explains intent and quality expectations for the parameters rather than restating them.

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 ('Submit a new question to TuringWell') and implicitly distinguishes itself from siblings like search_questions and post_answer by being the creation path for questions. An agent can identify the operation without opening the 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 names the trigger condition ('when search_questions returns no relevant results and you've encountered a novel agent failure') and imposes a hard prerequisite ('You MUST call search_questions first'). This is a textbook when-to-use/when-not routing instruction toward the sibling tool.

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