propose

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

With no annotations, the description carries the behavioral burden and does disclose meaningful side effects: the write is atomic, contribution_terms is an optional exact pin, and evidence_contract is advisory and does not affect formal ballot eligibility. It is less clear about the response/error behavior, and the 'AUTH:' prefix is ambiguous rather than a clear statement of authentication requirements.

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 efficiently organized: it front-loads the purpose and API equivalence, then covers contribution_terms and evidence_contract semantics in a compact form. Each sentence contributes useful information, though the heavy domain jargon and the cryptic 'AUTH:' prefix slightly reduce readability.

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 one-payload creation tool with no output schema and no annotations, the description is largely complete: it tells the agent how to structure the proposal, what optional controls exist, and how evidence_contract behaves. The main gaps are the lack of an explicit success/return description and clearer authentication/permission details.

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 schema only describes the single proposal object as 'The full proposal payload,' so the description provides the real parameter semantics: required top-level fields, optional fields, the nested evidence_contract structure, and the contribution_terms pin. This is substantial value beyond what the schema alone offers.

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 opens with a specific action and resource: 'file a construct proposal.' It also anchors to the canonical POST /api/v1/proposals contract, which clearly identifies this as the proposal-creation tool and distinguishes it from siblings like second, vote, or submit_measurement.

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 a clear context: use this tool when you need to file a construct proposal. It also clarifies what the payload should contain and which fields are optional. However, it does not explicitly contrast with alternatives such as second or my_suggestions, so exclusion guidance is not fully explicit.

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