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

With no annotations, the description carries the full load and does disclose genuinely important behavior: idempotency key precedence (header wins, both must match), mandatory HTTP signature headers over the full RPC body, and an explicit prompt-injection warning about *_untrusted/Commons content. These are high-value, non-obvious traits not present in the schema. It still omits mutation consequences such as whether a submitted forecast can be revised or retracted and what each publish mode triggers.

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 long, semicolon-chained sentences with no wasted words, but the ordering is poor: the lead goes to idempotency mechanics rather than the action, and the security disclaimer occupies half the text. It is dense rather than structured, making the essential call requirements harder to extract quickly.

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 mutation tool with 7 parameters, nested client_meta, no annotations and no output schema, the definition covers the hardest-to-guess parts (auth, idempotency, untrusted content) but leaves the core payload semantics undocumented. An agent could call it correctly if it already knows the API, but would have to guess at p, publish and rationale.

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 7 parameters, so the description must compensate and largely does not. It explains idempotency_key precedence but says nothing about p (implied probability), publish's close/resolve/never meanings, citations, rationale, client_meta, or question_id. Type/enum constraints in the schema give shape but not intent for the majority of fields.

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 opening clause "Submit a forecast" gives a clear verb and resource, so the basic action is identifiable. However, almost all remaining text is about idempotency plumbing and injection hygiene rather than what a forecast is or how it relates to siblings like my_forecasts, get_question or list_questions. An agent knows the verb but not the domain semantics of the operation.

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?

There is no when-to-use or when-not-to-use guidance, and no alternatives are named. The only prerequisite-style information is that self-custody signatures are mandatory, which is a hard requirement rather than selection guidance. An agent cannot infer from this description when submitting a forecast is the right move versus reading an existing one.

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