Tips & tricks for agents
Field notes for working efficiently against SparkleTree. Assumes you’ve read install.md.
Discover, don’t guess
Section titled “Discover, don’t guess”Read mosaic://capabilities at session start. It is the live matrix of enabled tools, server prompts, and recommended flows for this workspace. Feature availability varies by workspace and plan; the capabilities resource is authoritative where your assumptions are not. For profile discovery, get_platform_info with topic: "tool_profiles" lists what’s behind each ?profile= value.
Keep analytics lean
Section titled “Keep analytics lean”query_analytics defaults sections to ["summary"]. Stay there. Request additional sections only when the task genuinely needs them — wide section lists cost latency and flood your context with data you’ll summarize away anyway. Ask narrow, then widen.
Paginate with cursors
Section titled “Paginate with cursors”List actions (query_campaigns, query_products, and friends) use cursor pagination. Follow the cursor until exhausted rather than assuming the first page is everything — and don’t fetch every page when the first one answers the question.
Generation is async — poll, don’t spin
Section titled “Generation is async — poll, don’t spin”generate_campaign and render_video return before the work finishes. Poll query_campaigns (action: generation_status) or query_video (action: progress) at a reasonable interval. Do not tight-loop, and do not re-issue the start call because a poll came back “still running” — you’ll start a second paid job.
Publishes propagate themselves
Section titled “Publishes propagate themselves”publish, deploy, and deployment updates trigger republish of the affected surfaces. There is no separate flush/sync/cache-bust step. If you just published, it’s propagating — don’t hunt for an extra action.
Auth and rate-limit contract
Section titled “Auth and rate-limit contract”401mid-session: your token expired or was revoked. Re-run the OAuth bootstrap (the 401 carries resource metadata; spec-compliant clients recover automatically).429: back off exponentially and retry. No numeric rate limits are published — treat 429-with-backoff as the contract and don’t hardcode assumed limits.
Profiles are visibility, not permission
Section titled “Profiles are visibility, not permission”?profile=<name> changes which tools your session sees, nothing else. Same account, same workspace, same role-based permissions on every profile. Switching profiles will never grant access you don’t have — and never treat a hidden tool as a security boundary.
Prefer public surfaces for read-only brand questions
Section titled “Prefer public surfaces for read-only brand questions”If the task is “answer questions about this brand” or “fetch this brand’s published content,” you don’t need MCP, OAuth, or an account. Every published brand host serves /llms.txt, markdown twins of its pages (Accept: text/markdown), and a POST /ask concierge — all public. Cheaper, faster, no auth ceremony, no workspace scoping to think about. Reserve the MCP server for operating a workspace: creating, editing, publishing, analyzing.
Confirm before mutating or spending
Section titled “Confirm before mutating or spending”Worth restating from ready-prompt.md because it’s the contract users expect: readOnlyHint: true tools are free to call; manage_* mutates live marketing and generate_campaign / render_video cost credits. Confirm with your user before create, delete, publish, deploy, or any credit spend.