{"id":14827,"plugin_id":"plugin_asdk_app_6aa7b09b97808191b0ced38534cd8782","kind":"skill","collection_source":null,"comparison_source":null,"observed_at":"2026-09-30T23:10:15.341Z","digest":"e3c3524f133c1ea07d245fca0058b3d02d0a5917fc41b5e5b15d395660e4920a","against":null,"payload":{"description":"The shared rules every Wingspan tool call follows: ids, paging, previewing a write, and what the tools cannot do. Load this before any Wingspan tool call, and whenever someone asks about the people they pay through Wingspan, what they owe, onboarding paperwork, invites, invoices or payments — for example \"who do we pay\", \"what do we owe this month\", \"is this contractor ready to be paid\", \"add these contractors\", \"log a payment\", \"why has this not been paid\".","included_files":[{"relative_path":"agents/openai.yaml","size_in_bytes":344},{"relative_path":"references/glossary.md","size_in_bytes":4881}],"name":"using-wingspan-tools","skill_md_contents":"---\nname: using-wingspan-tools\ndescription: >-\n  The shared rules every Wingspan tool call follows: ids, paging, previewing a write, and what the tools cannot do. Load this before any Wingspan tool call, and whenever someone asks about the people they pay through Wingspan, what they owe, onboarding paperwork, invites, invoices or payments — for example \"who do we pay\", \"what do we owe this month\", \"is this contractor ready to be paid\", \"add these contractors\", \"log a payment\", \"why has this not been paid\".\n---\n\n# Using the Wingspan tools\n\nWingspan is a payments platform. A company that pays people uses it to bring\nthose people on board, collect their tax and compliance paperwork, and pay\nthem. This plugin gives ChatGPT read access to that company's own records, plus\nthree carefully limited write actions.\n\n## Words used throughout\n\n- **Payer** — the company doing the paying. Everything here is written from\n  the payer's side.\n- **Contractor** (called a *payee* inside Wingspan) — a person or business the\n  payer pays.\n- **Engagement** — a named working arrangement a contractor is assigned to,\n  such as \"Q3 copywriting\" or \"Design retainer\". Payments are filed under an\n  engagement, and requirements can be attached to one.\n- **Requirement** — something a contractor must satisfy before the payer can\n  pay them: a tax form, a signature, an insurance certificate, a background\n  check. A requirement the payer configured is a *definition*; one contractor's\n  copy of it is an *instance*.\n- **Payable** — one payment owed to one contractor. In the Wingspan app this is\n  a row on the Payables screen.\n\nThese tools answer only for the company doing the paying. If you want to know\nwhat someone owes you, they cannot answer it.\n\nFor unfamiliar terminology, read [references/glossary.md](references/glossary.md).\n\n## The ten tools\n\n| Tool | What it answers | Reads or writes |\n| --- | --- | --- |\n| `who_am_i` | Does the connection work, and which account is it reading? | Reads |\n| `search_contractors` | Who do we pay? Who matches this name? Who is held up? | Reads |\n| `get_contractor` | Can we pay this one contractor, and if not, why? | Reads |\n| `search_requirements` | What must a contractor satisfy before we can pay them? | Reads |\n| `search_payables` | What do we owe, and what have we paid? | Reads |\n| `get_payable` | What happened to this one payment? | Reads |\n| `get_payroll_preview` | What would the next payroll run pay, as things stand today? | Reads |\n| `create_contractors` | Create contractors, assign an engagement, send invites. | **Writes** |\n| `create_payables` | Log payments as drafts. | **Writes** |\n| `open_payables` | Release drafts so contractors can see them. | **Writes** |\n\nIn a tool list these appear as `mcp__codex_apps__wingspan_mcp2_who_am_i` and so\non. Reason about the short names above.\n\nUse the available Wingspan-MCP2 tool schemas for exact arguments; tool prefixes can vary by host. If a schema differs from a field list below, follow the current schema.\n\n## Rules for every call\n\n**Use the id the search gave you.** Each row from `search_contractors` carries\na `contractorId`, and each row from `search_payables` carries a `payableId`.\nThose are the ids `get_contractor` and `get_payable` accept. Ids copied from\nanywhere else — a spreadsheet, a URL, another system — will usually be\nrejected.\n\n**One page per call.** `search_contractors` and `search_payables` return a\nsingle page, then hand back `pagination.nextPageArgs`: the complete set of\narguments for the next call. Show the page to the user and offer to fetch the\nnext one. Do not loop through pages unasked. A page token only works with the\nexact same filters and sort that produced it, so pass `nextPageArgs` back\nunchanged.\n\n**Read the `note`.** Every list result carries a plain-sentence `note` saying\nhow many rows came back, how the list was sorted, and what to do next. It also\nwarns about things that are easy to misread, such as a filter that cannot\nreturn what the user expects. Pass that on rather than dropping it.\n\n**Preview, show, confirm, then apply.** All three write tools default to\n`mode: \"preview\"`, which changes nothing: it looks up every id, checks every\nrow, and reports exactly what applying would do. Always preview first, show\nthat preview to the user in full, and wait for them to say yes. Only then call\nagain with `mode: \"apply\"` and a `requestId` you have not used before. Never\napply on your own initiative, and never apply without having previewed the same\nrows.\n\n**Pass the preview token.** Every apply requires the matching preview's `confirmationToken`, passed back verbatim with the same previewed arguments. Never construct a token. A missing, altered or expired token requires a new preview. For explicit `open_payables` rows, also return each preview's `ifMatch` fingerprint unchanged; if the selection or records changed, preview again before applying.\n\n**Reuse `ref`, and pick a fresh `requestId` per attempt.** Each row in a\n`create_contractors` or `create_payables` call has a `ref`, your own label for\nthat row. Results come back by `ref`, and the safety mechanism that stops a\nretry from creating duplicates is built from `ref` plus `requestId` — so send\nthe *same* refs on apply that you sent on preview. Retrying an apply with the\nsame `requestId` and the same refs returns the result of the original writes;\nnothing new is created. A genuinely new attempt gets a new `requestId`.\n\n`open_payables` works the same way but has no `ref`: its rows are payments that\nalready exist, so it reports each one by `payableId`, and that id is what its\nretry key is built from. Listing the same `payableId` twice in one call is\nrefused.\n\n**Amounts are in dollars.** `1200.50` means one thousand two hundred dollars\nand fifty cents. Never send cents.\n\n**Payments are created as drafts.** `create_payables` stops at a draft the\ncontractor cannot see, with no payment scheduled. `open_payables` releases it,\nwhich is what shows it to the contractor. Approving it and paying it happen in\nthe Wingspan app.\n\n**Some things are deliberately out of reach.** Any action Wingspan protects with\nan extra identity challenge — paying a payable, paying an invoice, moving money\nbetween accounts, creating or rotating an API key — cannot be done from here at\nall, because there is nowhere in this conversation to complete that challenge.\nSay so plainly and point the user at the Wingspan app rather than looking for a\nworkaround.\n\n**Child accounts.** Nine of the ten tools take an optional `accountId`,\nwhich acts as one child account of an organization instead of the signed-in\naccount. `who_am_i` takes no arguments at all. Only use `accountId` when the\nuser names a specific child account; `who_am_i` lists the ones reachable.\n\n## Do not confuse these\n\n- **An invoice is not a payable.** A payable is the payer's record of what it\n  owes one contractor. An invoice is a bill, and either side can raise one: a\n  contractor billing the company, or the company billing its own client.\n  Payables can originate from either kind of invoice as well as from payroll,\n  and all of them show up in `search_payables` — the individual payments from a\n  payroll run appear there, the payroll batch total itself does not. A payable\n  that came from an invoice is owned by Wingspan and cannot be edited here.\n- **A requirement definition is not one contractor's progress.**\n  `search_requirements` lists the payer's templates. One contractor's progress\n  against them comes from `get_contractor`.\n- **A relationship id is not an account id.** A `contractorId` identifies the\n  payer's record of that contractor, not the Wingspan account the contractor\n  signed in to. Only `accountId` takes an account id.\n\n## Finish these in the Wingspan app\n\nThe tools cannot do any of the following, and no combination of them adds up to\nit. Tell the user which screen to go to instead.\n\n- Creating or editing engagements, worksites, groups, custom fields, rate cards\n  or requirement definitions.\n- Attaching a requirement to an engagement or a group, and approving,\n  rejecting, resetting or renewing one contractor's requirement.\n- Approving, scheduling, cancelling or paying a payable; funding sources;\n  starting a payroll run; invoices; payment splits; accounting integrations.\n  Releasing a draft is the one step here that is not app work — that is\n  `open_payables`.\n- Re-sending, retargeting or cancelling an invite.\n- Everything the contractor does themselves: signing up, signing a document,\n  uploading a certificate, verifying their identity, adding a payout method.\n- Sharing tax information, which is usually the contractor's step; a company\n  that records and verifies a contractor's taxpayer details itself also does\n  that in the app.\n\n## Where to go next\n\n- Finding and filtering contractors, and who is held up:\n  the `finding-contractors` skill.\n- What is owed, and what happened to one payment: the `checking-payments` skill.\n- Adding contractors: the `onboarding-contractors` skill.\n- Creating draft payables: the `creating-draft-payables` skill.\n- Connection problems and wrong-account answers: the\n  `troubleshooting` skill.\n"},"changes":[],"summary":"First saved snapshot. No earlier version is available for comparison.","summary_kind":"deterministic","summary_metadata":{}}