Proposed work: add input schemas for all MCP tools

[xyjk0511]

Problem

The live MCP tools/list metadata currently publishes a machine-readable inputSchema only for submit_work_proof. Other MCP tools advertise argument-taking behavior in descriptions, but do not expose schemas for agent callers to validate against before calling.

This affects read-only tools such as list_bounties, get_bounty, list_bounty_attempts, get_ledger_entry, get_proof, get_wallet, and get_balance, and write-capable tools such as register_wallet and submit_wallet_transfer. Agents have to infer arguments from prose docs or trial-and-error, even though the handlers already validate these arguments internally.

Evidence

• Live tools/list from https://mcp.mrwk.online/mcp shows inputSchema only on submit_work_proof; the other tools have name and description only.
• Current source has the same shape in app/mcp.py: only submit_work_proof includes inputSchema.
• Current app/mcp_tools.py already enforces argument types and bounds for the other tools, including positive integer ids, bounded limit, enum-like status, boolean flags, wallet addresses, proof hashes, ledger sequence, and signed transfer fields.
• Public docs describe MCP usage and arguments manually, but MCP metadata is not yet the complete contract for agent callers.

Proposed work

Add conservative inputSchema metadata for every MCP tool that accepts arguments, aligned with existing handler validation.

Examples:

• list_bounties: status, q, sort, limit
• get_bounty: id, include_awards
• list_bounty_attempts: bounty_id, include_expired, limit
• get_balance: account
• register_wallet: public_key_hex, optional label
• get_wallet: address
• submit_wallet_transfer: signed transfer fields already required by the handler
• get_ledger_entry: sequence
• get_proof: hash

Add focused tests that tools/list includes schemas for all argument-taking tools and preserves the existing submit_work_proof schema. A short docs note can point agent callers to MCP metadata as the argument contract.

Expected value

• Agents can validate tool arguments from MCP metadata instead of scraping docs or probing invalid calls.
• Existing server-side validation stays the source of truth; schemas mirror behavior rather than changing behavior.
• Future MCP clients get a more complete contract for generated forms, typed wrappers, and preflight checks.
• Maintainers get tests that prevent new argument-taking tools from being added without a schema.

Relationship to related proposals

• Proposed work: add typed OpenAPI response schemas for public MRWK read APIs #688 covers typed OpenAPI response schemas for REST read APIs. This issue is specifically MCP tools/list argument metadata.
• Proposed work: align generic work-proof JSON availability keys #698 covers submit_work_proof JSON output shape. This issue covers input schemas across MCP tools.
• Proposed work: expose structured submission mode for non-PR bounties #676 covers structured submission mode/expected artifact for bounty rows. This issue does not change bounty rows.
• Proposed work: clarify partial pending-payout availability guidance #697, Proposed work: use effective availability in submission quality gate #681, Proposed work: add availability-state breakdown to bounty summary #682, and Proposed work: add effective-availability filtering to bounty discovery #683 cover effective availability guidance/filtering. This issue is about MCP tool contracts.

Possible acceptance criteria

• Every MCP tool with required or optional arguments has an inputSchema in tools/list.
• Schema constraints match current handler validation where practical.
• submit_work_proof keeps its existing schema behavior.
• Tests fail if an argument-taking MCP tool is missing schema metadata.
• No ledger, payout, treasury, wallet-signature, proof, bounty acceptance, or private-data behavior changes.

Evidence or tests required

• Call tools/list locally or in tests and assert schemas are present for all argument-taking tools.
• Run focused MCP route/tool tests that cover the schema list.
• Run existing tests for call_mcp_tool behavior to confirm runtime validation did not change.
• Optionally run docs smoke if a documentation note is added.

Duplicate search

I searched for existing issues using phrases including:

• MCP tools input schemas
• inputSchema MCP
• tools/list schema
• MCP tool schema

I did not find an existing proposed-work item for full MCP argument schema coverage. Related but distinct work is #688, #698, #676, #697, #681, #682, and #683 as described above.

Out of scope

• No new MCP tools.
• No change to runtime validation semantics unless needed to make schemas accurately match current behavior.
• No changes to ledger entries, bounty payouts, proof creation, treasury proposals, wallet signatures, balances, exchange, bridge, cash-out, private security handling, or fabricated paid-work status.
• No private contact or private payment-channel behavior.