Finding contractors
The shared rules for every call — ids, paging, previewing a write, what the
tools cannot do — are in the using-wingspan-tools skill. Apply them here.
A contractor is a person or business the company pays; Wingspan also calls this a payee. An engagement is a named working arrangement a contractor is assigned to. A requirement is something a contractor must satisfy before they can be paid, such as a tax form or an insurance certificate.
Two tools cover this: search_contractors lists and filters, and
get_contractor reads one contractor in full. Every row a search returns
carries a contractorId, and that is the id get_contractor takes.
Listing and searching
search_contractors with no arguments lists active contractors, newest first,
25 to a page.
There are no other filters. Do not invent one.
Two separate questions, two separate arguments
status is the tab strip from the Wingspan app, and it mixes the working
relationship with paperwork: incomplete and complete are a summary of
requirements, while notSignedUp and archived are about the relationship.
onboarding is the relationship on its own, and every row reports it whatever
you filtered on.
The two combine, so status: "notSignedUp" with onboarding: "Pending" means
"invited, has not signed up". One pair is refused rather than answered:
onboarding: "Inactive" together with status: "active", because active
excludes archived contractors and Inactive requires them. status defaults
to active, so leaving it out is the same pair — send onboarding: "Inactive"
with status: "archived".
One more thing worth passing on: onboarding: "Inactive" matches archived
contractors, but a contractor who only rejected their invite is not matched.
The underlying search cannot express "archived or rejected" in one query, and
the result's note says so.
One kind of contractor no filter finds: someone archived before any
engagement was assigned to them. Every status tab except active needs a
paperwork or engagement summary they never got, and active excludes anyone
archived — so no combination of status and onboarding returns them. Read one
with get_contractor if you have their contractorId; its headline reads
Archived. Every row that does come back carries its own archived field,
whatever you filtered on.
Who still has a named requirement outstanding
Two calls, in this order.
search_requirementslists the requirements the company has configured. Each carries arequirementDefinitionId, theblockingvalue Wingspan holds for it, its grace period and how often it expires. Pick the one the user named. With no arguments it lists the ones still in use; it also takestype(one kind of requirement),includeInactive(show retired ones too),limit,pageTokenandaccountId, and nothing else.search_contractorswithrequirementset to that id; its exact name also works, matched case-insensitively and in full, so a partial name will not resolve. SetrequirementStateto the state you want.
A requirement the company rejected, or one whose underlying record was revoked or failed, is reopened rather than failed — it reads as outstanding again, with a reason recorded. There is no failed state. Say "reopened after review" rather than "never started" when reporting one.
requirementState on its own is refused: it needs requirement.
Two things to say out loud when reporting the answer:
- Not every outstanding requirement blocks a payment.
blockingon a definition is what Wingspan reports for that definition. A contractor's own copy can be blocking or not depending on where it was attached.get_contractortreats every incomplete requirement as blocking and does not read that setting; which placement merely tracks a requirement is visible only in the Wingspan app. gracePeriodDaysis a delay on the definition, not a verdict about a person: it is the days from when a requirement is attached to a contractor before an outstanding copy starts holding up a payment. Inside that window an unfinished requirement does not block.
The catalogue of requirement kinds, and what has to happen for each:
${CLAUDE_PLUGIN_ROOT}/skills/finding-contractors/requirement-types.md
When to read one contractor in full
Move to get_contractor once the question is about one person: "can we pay
them", "what is their status", "what is missing". It returns what the
Contractors detail screen shows, and the field to lead with is alert — the
screen's single verdict, with exactly one of these outcomes:
Only one applies, and the order above decides which. A contractor who is both archived and missing tax information reads "Tax information not shared", because that check comes first. There is no single "can I pay this person" field anywhere in Wingspan; this verdict is the closest thing to one.
"Tax information not shared" does not always mean the contractor must act — a payer can supply and verify the details itself, in the Wingspan app.
alert can also be empty, when none of the checks above fire. Report that as
"nothing flagged" and fall back to the assignments and requirement list in the
same result rather than declaring the contractor payable.
get_contractor also returns their tax information and its verification
status, every engagement assignment with a count of outstanding requirements,
the full requirement list with expiry dates, whether they have a payout method
set up (somewhere for the money to land), and your own id for them.
Two results to read carefully
A contractor with no engagement assignment has no paperwork summary at all.
Their requirements, tax-ID and engagement status are not recorded rather than
empty, and the notSignedUp, incomplete and complete tabs will not return
them. The result's note says so when it applies. Assigning an engagement is
what gives them a status worth reading, and that is app work.
An assignment with no requirements shows "None required". It also shows whatever eligibility Wingspan reports. Do not infer from it. If such a contractor cannot be paid, the fix is to attach one requirement in the Wingspan app and have it completed; nothing else re-evaluates eligibility.
A search that finds nobody
If a name search returns no rows and archived contractors were excluded, the result reports how many archived contractors do match. Offer to look there before telling the user the person does not exist.
Finish these in the Wingspan app
- Creating or editing engagements, groups, worksites, custom fields and rate cards.
- Writing a requirement definition, and attaching one to an engagement or a group.
- Approving, rejecting, resetting or renewing one contractor's requirement, and extending an expiry date.
- Archiving or restoring a contractor.
- Everything the contractor does themselves: signing up, signing, uploading a document, verifying identity, adding a payout method.
- Sharing tax information, which is usually the contractor's step; a company that records and verifies a contractor's taxpayer details itself also does that in the app.