create_pending_proposal

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

With no annotations, the description carries the full burden and does so well: it discloses input normalization (private tags stripped from proposed_text and metadata), a non-obvious splitting behavior (a full rendered atomic block is split into body + metadata), scope inheritance for updates, the absence of writes to rules/lessons/.md, and the access level ('analyze'). These are exactly the side effects an agent needs before calling.

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-loaded with the core action and densely informative, with each sentence covering a distinct behavior. The body/metadata sentence duplicates guidance already in the schema, and the returns/access-level lines are slightly tacked on, so it is a touch redundant rather than maximally tight.

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 9-parameter mutation-style tool with no annotations, the description covers the critical unknowns: input tampering (tag stripping), the update path's referential precondition, scope inheritance, what is NOT written to disk, and the follow-up tool. An output schema exists, so its brief return note is a bonus rather than a necessity.

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 100%, so the baseline would be 3, but the description adds genuine semantics beyond the schema: it explains the body-vs-metadata division and the atomic-block splitting rule that governs how proposed_text is parsed, plus the target_id prefix constraint. This meaningfully reduces ambiguity about how to populate the two primary 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?

States a specific verb+resource ('Validate and persist a pending proposal') and enumerates the three types it accepts. It also draws a bright line against the sibling that actually commits changes ('Does not write to rules/lessons ... approve_proposal does that'), so an agent can place it precisely in the workflow.

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 makes the pipeline clear: this creates a pending proposal that requires human review, and approve_proposal is what promotes it. It also gives a conditional precondition (for type='update', target_id must reference an existing RN-*/LL-* id). It doesn't compare against edit_proposal/reject_proposal, but the create-vs-approve contrast is well established.

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