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

The annotations only say readOnlyHint=false and openWorldHint=true. The description goes far beyond that: it discloses the API key requirement, the relevance-match mechanism gated like search, the cap of 50 matched sellers receiving job.matched events, bid delivery via job.bid events, acceptance through buy_url payment, and the job.close workflow. It also warns that title and brief are echoed under _untrusted, which is valuable trust-relevant context.

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 tightly organized: purpose first, then parameters, then matching/event behavior, then the bid-to-close workflow, then the reply format and untrusted echo. Every sentence earns its place and no information is repeated from the schema verbatim.

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?

With no output schema, the description explains the reply shape (job_id, status, expires_at, matched_sellers) and the _untrusted echo. It covers the full lifecycle from posting through bidding to closing, names the relevant sibling tools, and addresses retries via idempotency. Nothing essential for correct invocation is missing.

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 is 3, but the description adds substantial semantics on top: the 30-day default deadline, the brief's role in seller matching, the matching itself, the budget unit, and a deep explanation of idempotency_key including retry behavior and conflict cases. This meaningfully exceeds what the JSON schema alone conveys.

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 trigger condition ('No listing fits?') and a clear verb-resource pair ('Post the work and let sellers bid'). It explicitly contrasts with createListing by framing this as the alternative when a fixed listing doesn't fit, so an agent can distinguish postJob from its siblings without opening any schema.

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 first sentence states the when-to-use condition ('No listing fits?') and preconditions ('needs your API key'). It also names the companion tools that complete the workflow (searchJobs, getBids, closeJob) and their roles. It stops short of an explicit 'do not use when...' exclusion, but 'No listing fits?' is a clear enough discriminator against createListing.

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