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

Goes well beyond the annotations (readOnly=false, idempotent=true, destructive=false) by disclosing that unsent fields are preserved, that nothing is sent to anyone, the exact 400 TYPE_IS_FIXED failure, the auth scope required, and the sign-in prompt behavior for unconnected members. It also flags user-generated text as data rather than instructions, which is material for an agent handling member content.

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 the partial-update rule, then permissions and failure modes. Sentences are dense but each carries content; the prompt-injection disclaimer is boilerplate-ish but relevant to a tool that ingests member-written text.

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 no output schema, the description covers preservation semantics, permissions, auth flow, and a key error case. It does not describe what the response returns (e.g., the updated draft or a validation summary), which is the main remaining gap.

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?

Measured schema coverage is 50%, but the schema itself carries dense per-field documentation (type-specific fields, enums, ranges, cross-field requirements like benefits needing contractToHire). The description adds only the type-immutability rule and the partial-update semantics; it contributes little beyond the schema for individual 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 and resource ("Update a Post Work draft") and immediately clarifies that this is a partial update — only the fields sent change. That distinguishes it from draft_work_posting, delete_work_draft, and submit_my_draft, though no sibling is named explicitly.

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?

Gives clear operational context: send only the fields to change, the draft type is immutable, and the call requires the work:write permission scope. It does not name alternatives or say when a draft should be submitted vs. updated, which keeps it below a 5.

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