Row sources

Choose and attach a source

Use tables.findable_catalog.list for the compact source list: id, label, produces, pricing, readiness, and when to use it. Pass definition_id to read one source's inputs and output fields, then add it with tables.table_sources.attach. When the user provides a LinkedIn search URL, attach provider.linkedin.people.search_by_url with raw_search_url set to that URL. Use provider.linkedin.people.search only when building a search from words. Do not pass columns to copy source fields; reference {{source_key.field}} in prompts and formulas.

Architect uses the list-building skill to begin with purpose, qualification evidence, disqualifiers, and the distinction between required and nice-to-have criteria. It chooses the route that can carry the scarcest criterion or strongest signal. Intent is not itself a source field, so Architect translates it into observable evidence before choosing a route.

Put every stated criterion into the source input that supports it. A location is a location filter, a title is a title filter, and a size is a size filter. A criterion omitted from source inputs is not applied. A guessed filter value may not fail, but it can return the wrong rows, so plan output and a landed sample both need inspection.

For hiring intent, the plan starts with qualifying company rows and then follows with people at those companies. The people follow-up projects current title, person location, and profile URL. Keep the company hiring role separate from the titles of people to contact. Passing person titles as a company hiring role can return companies hiring the wrong role.

Attach the exact planned binding

tables.table_sources.attach binds one provider fetch, canonical producer, or CSV file to a worksheet. Attachment writes the binding row only. It fetches no rows and spends no credits. The operation is a free, internally reversible draft write, so a missing connection does not prevent you from authoring the worksheet and its source.

Attach the plan route's exact binding_spec, including its definition_id and input_bindings. Do not attach an empty binding. The attach response lists available_output_paths for every field. field_guidance names a few relevant {{source_column_key.field}} references. Pass paths in columns only when the caller wants them as their own formula columns. Omit columns and only the source column is created. project_fields does not add columns.

The response is the full source record, not a signal that rows landed. It includes source_id, workspace and table ids, source column and tool ids, output row kind, the canonical upsert key, binding, state, frontier, timestamps, and archive state. Use tables.table_sources.list, a free read-only capability, to inspect sources bound to one worksheet before replacing a binding.

Preserve the one-source boundary

A worksheet has one row source. When the current worksheet is named by the user or is the active canvas, treat it as the target and add requested columns there. Do not create an empty workbook or worksheet merely because a source needs more work. Create another worksheet only when the request needs a new list or a distinct row type.

For a companies-then-people plan, keep the source chain visible. The company worksheet receives the qualifying signal. The people worksheet uses the company input named by the plan, so every person can remain linked to the company evidence. For people at companies already on a company worksheet, use the find-people action on that worksheet rather than manually creating, attaching, and running a second source. It creates or reuses the linked People worksheet and binds the company input.

To continue a list, run the attached source again. A company-scoped people source resumes companies it has not searched yet. Re-attaching a source or changing its inputs starts it over, so do that only when the filters need to change. This distinction prevents an avoidable duplicate pass through rows that were already inspected.

Use real options offered by the source for locations, industries, companies, and schools. A source field can be narrow in meaning: a company-search location may mean headquarters, while a nested job location is the location of the matched job. Read the entities that landed before treating a route as a match for the user's place requirement.

Run a small source sample

tables.table_sources.run executes the bound source for real. It can call an external provider and spends variable credits. The executor reserves max_credits, or max_units, before dispatch. The capability applies a generic maximum of 25 credits per call, but that clamp is not the actual provider price. The actual cost belongs to the bound executable.

The run result returns run_id and status. On the authority path it also returns state_version, authority_version, authority_digest, policy_trigger_id, selection_snapshot_id, and replayed. A queued response confirms that execution was requested. It does not prove the source supplied the intended people or companies.

Run a small batch first. The list-building skill uses about twenty-five rows as a sample, reads the entities rather than only their count, and can compare two or three parameter variants. Keep the most precise variant. The sample should make most rows right at the source before you add expensive columns or request a larger run.

Read the landed rows before scale

Read rows, not only counts. A count that is still being computed is unknown, not zero. Check the selected entities, their locations, the proof for the qualifying signal, and fields needed by later columns. If the sample contains global companies because a company location meant headquarters, or it contains a keyword match without the requested meaning, the source filters are too broad or incomplete.

Try a corrected input on a small sample. Do not make the next step more expensive until the source entities are precise. When the sample reads correctly, scale the same source to the requested count. If no target was stated, the list-building skill uses 100 rows. Target qualified rows, not merely landed rows: a source that lands many near misses still needs a narrower route or filter.

Read the source result after the run finishes, then read the worksheet page. In the completion report, separate landed rows, duplicates, empty evidence, and failures. The next layer should be a column that changes the qualification decision. A source that produces the right raw rows does not remove the need to inspect the cells created by later columns.

When a source does not run

A missing account or credential blocks a run, not planning or attachment. Keep the planned binding, state that it can be attached now and connected or bound at run time, and do not switch to a weaker source merely to avoid a connection. Building every planned step while a connection is unavailable leaves the worksheet ready for a later run.

If the contract refuses the attachment with repair.kind set to fix_input, use repair.hint to correct the payload and retry the corrected binding. If a required criterion has no source filter, retain it for a column and score condition instead of claiming the source applied it. If a cell later reaches a daily limit, that is the workspace pacing cap, not a source defect.

Queued, paced, capped, and unknown are not automatically failures. Read the run state again and inspect the source record frontier before retrying. Do not re-attach a source to solve a temporary run state: reattachment changes the source chain and can start the list over. Diagnose the missing connection, input, or field reference, correct that cause, and read the next sample.

• Keep a missing credential separate from an invalid source binding.
• Keep an unsupported filter separate from a source-run state.
• Keep a queued run separate from a failed row result.
• Keep the source record as evidence for the next diagnosis.