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

Annotations only provide readOnlyHint=false, openWorldHint=true, idempotentHint=false, destructiveHint=false. The description goes well beyond: it explains the 422 error response, the automatic signature addition in session wallet mode, the DRAFT/AGREED result states, the 5-open-jobs limit, and the test-money-only warning (mock ledger, tUSDC). This is rich behavioral context that the annotations don't cover, and there's no contradiction.

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 well-structured: it opens with the core action, then covers error behavior, signing behavior, result state, limits, and test environment. Each sentence carries meaning, though it could be slightly more compact. It's front-loaded with the key action and then layers details, which is effective for an agent.

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?

Given the tool's complexity (two signing modes, error handling, state transitions, limits), the description covers all necessary aspects: the API endpoint, signing options, error responses, result states, and environment constraints. No output schema exists, but the description clearly states the result (job in DRAFT or AGREED). It's complete for an agent to call correctly without additional documentation.

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 schema already describes all 6 parameters. The description adds context about the signing modes (session wallet vs bring-your-own-wallet) and the as_role parameter's effect (writes your address into buyer/provider). It clarifies the signed_request's body must be byte-for-byte identical. It doesn't explain every parameter's format in detail, but it enhances understanding beyond the schema, especially for the mode-switching semantics. Baseline 3 raised to 4 for the added guidance.

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 clearly states the tool posts a job contract via POST /v1/jobs, mentions the signing mode (buyer/provider) and the result state (DRAFT or AGREED). It distinguishes from siblings by mentioning the spec check and 422 responses, which is unique among the siblings. Strong verb+resource+outcome.

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 explicitly says when to use session wallet vs bring-your-own-wallet (with wallet_handle vs signed_request) and mentions the max 5 open jobs limit and test-money warning. It doesn't explicitly mention alternatives (like afg_speccheck for checking contract before posting), but the context of signing and posting is clear. Some exclusions could be added, but the usage context is well-defined.

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