Approve a proposal

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

Annotations already declare readOnlyHint=false, destructiveHint=true, and idempotentHint=false, which the description aligns with. It adds substantial behavioral detail beyond annotations: re-reads the billboard to detect stale proposals, re-checks MAX_BID_SOL and DAILY_CAP_SOL, executes and logs, and notes expiration and one-time approval. This gives the agent a full picture of side effects and safety checks 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 three sentences and front-loaded with the core action ('Sign a proposal...'). It packs important constraints (stale refusal, cap checks, expiry, one-time approval) without unnecessary fluff. Slightly dense but still efficient and scannable; a 4 rather than 5 because the permission-prompt note could arguably be placed earlier or streamlined.

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 single-parameter mutation tool with an output schema, the description covers all the essential behavioral context an agent needs: what it does, when it refuses, its side effects (executes and logs), and the specific conditions. The output schema presumably documents the return shape, so that is not required here. The description is complete for correct invocation.

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 already provides a description for proposal_id (returned by the proposal-creating tools), and the description reinforces this relationship. It adds context by specifying which tools produce the proposal and implicitly the type of ID expected, going slightly beyond the schema. Since schema coverage is 100%, the baseline is 3; the added explanation about the source tools lifts it to 4.

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 states a clear action ('Sign a proposal') with the specific resource (proposals from acquire_posting_rights, append_message, clear_message). It distinguishes this from siblings by naming the proposal-creating tools and framing it as the approval step, so an agent can tell it apart from the other calls without opening their schemas.

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?

It explicitly states when to use this tool: after creating a proposal, and specifically as the call to put a permission prompt on because the server cannot see the human. It also communicates usage constraints (expires after 10 minutes, can be approved once) and the conditions under which it refuses (stale proposal, cap violations). This gives clear when/why guidance and differentiates from the proposal-generation siblings.

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