Serre Connect tool reference

Every tool your assistant can use once it is connected to Serre, with the exact arguments each one takes. This page is generated from the connection itself, so it always matches what your assistant actually sees.

To set one up, see Connect an AI assistant (not yet published).

Reads are available to current workspace members with read or full-access keys. Writes are the guided build tools: full-access keys on workspaces enrolled in guided builds only, with enrollment re-checked on every call. Other workspaces keep using the Serre app to create, calculate, edit or share cases. Every call runs as the member who owns the key, inside their workspace only.

list_company_profiles#

Read. List or search the workspace's seller/company profiles, including each id and the informational default marker. Use the chosen id as companyId; a multi-company plan never chooses silently.

get_company_profile#

Read. Read one seller/company profile by id: identity, narrative and highlights, market context (industry, segments, target industries and personas, value focus), sizing, the pricing fields whose origin is that company profile, first-run onboarding state, a summary of its solutions with completeness status, and contentRevision — the base every profile, solution, driver-link and evidence write on this company presents. Foreign and deleted ids are not visible.

list_personas#

Read. List the workspace's persona library — the buying-committee seats the seller sells into — with each persona's deal role, research context, researched profile fields and revision (the base update_persona presents). Multiple personas can share a deal role, including economic buyer.

No arguments.

get_solution#

Read. Read one solution in full, including a cursor-page of value-model claims. Pass limit and nextCursor as cursor to continue. Also returns classification, value story, pricing, completeness, drivers, capabilities, conditions and evidence requirements, plus the company profile's contentRevision.

list_evidence#

Read. List or search the evidence library (case studies, analyst quotes, benchmarks, third-party studies) with the drivers each item backs. Pass companyProfileId to scope to one seller; omit it for the whole workspace.

get_onboarding_readiness#

Read. Read first-run readiness: whether the workspace has completed setup, and — for one company profile (the one setup would resume when omitted) — every gate with its status, reasons and the tool that closes it. Required gates (a named company, a classified solution, a driver linked to the flagship) must pass before complete_onboarding; recommended gates (market context, value story, committee, pricing, evidence) are reported, never enforced.

get_ai_job#

Read. Read a durable research job by id (the jobId research_company_profile returns): status, steps, whether it is terminal, designed failure copy, and — once it has settled — the reviewable draft payload to read back into the library with the write tools. Poll until terminal is true; a job never consumes an AI credit on read.

list_solution_taxonomy#

Read. Read the platform solution taxonomy a solution is classified against: every category with its subcategory slugs, or — given a category slug — that category's subcategories with their use cases. Use the slugs as category / subcategory / useCase in create_solution and update_solution.

get_value_capture#

Read. Read a value capture run: status and stage, the run revision, its sources, the settled proposal (claims, capabilities, conditions, evidence requirements with their review states) once ready, the apply preconditions apply_value_capture presents, and the reconciliation choices against claims already in the library.

list_value_drivers#

Read. List the workspace's reusable value drivers. Use these ids in create_business_case so the generated case carries real figures.

list_solutions#

Read. List this workspace's solutions with their linked value drivers. Use the ids when creating a business case.

No arguments.

list_prospects#

Read. List the workspace's accounts — the companies you sell to, which the API calls prospects — most recently updated first, each with its accountType and isTargetAccount.

get_prospect#

Read. Read one account's full buyer context, including its accountType and isTargetAccount.

get_case_results#

Read. Read a generated case's computed outputs (total benefit, ROI, payback, NPV, Monte-Carlo ranges) plus metric applicability/methodology, snapshot freshness (snapshot.buildFingerprint is the value run_quick_check takes), readiness and caveats, and the case's current inputsRevision and contentRevision for guided writes. A GENERATED status is not a completion receipt. Includes the workspace link and, if a live share token already exists, the public URL — this tool never mints one.

get_case#

Read. Read a case's editable copy and private language state plus its current inputsRevision and contentRevision: the current effective fields with canonical fallback, the applied copy revision and private language revision, the live snapshot binding, field destinations, pending case_copy proposal ids, the delivered copy revision, validation/freshness and the read-only metric catalog. Feed those revisions into propose_case_copy. Computed outputs live in get_case_results.

plan_business_case#

Read. Plan a complete business case from an account WITHOUT changing anything. Returns status 'succeeded' with the plan, the estimated cost and a signed planToken for execute_case_plan (executionAvailable says whether this workspace is enrolled for guided writes), or 'needs_choice' (which account?) / 'needs_confirmation' (create this account?) with the question to put to the user. Ask the user, then call again with their answer (prospectId for a choice; createProspect: true to confirm creation). Give a website when you have one — it identifies a company more reliably than its name. In a multi-company workspace you must first list/search company profiles, ask which seller to use, and pass companyId.

get_library_agent#

Read. Read the library agent's saved actions, refusals, source quotes, proposed content and exact review fingerprint. Only the owned tenant run is readable.

create_prospect#

Write. Create an account record (guided; the API calls it a prospect). Reports which identity fields are still missing so you can supply sourced context. A duplicate name or website is refused and names the existing account. Optional accountType (PROSPECT | CUSTOMER, default PROSPECT) and isTargetAccount (default false) are the seller's own labels.

update_prospect_context#

Write. Correct or extend one account's buyer context (sizing, priorities, industry, website, accountType, isTargetAccount). Supply the context revision you read; a stale one is refused so a teammate's edit is never overwritten. Deal-only context belongs to a business case, never here.

enrich_prospect#

Write. Research one account through the enrichment waterfall. The run is durable and the drain completes it — read the account afterwards for what was found. Failed or partial research keeps whatever was already on the record.

start_case_build#

Write. Start (or resume) the case build from a signed plan token: creates the account if the plan said so, then the draft case with EXACTLY the plan's solutions and drivers — nothing automatic, no calculation, no charge. Replays resolve to the same build. To add work after budget exhaustion, re-plan and call again with amendOperationId plus expectedPlanVersion.

cancel_build_operation#

Write. Cancel your own case build (or one a teammate started, if you are an admin or owner). Queued steps stop; steps that already committed stay committed. A cancelled build cannot be resumed — start a new build instead.

set_case_profile#

Write. Generate the case's buying-committee profile from the reviewed committee (uses 1 AI credit when it generates), or correct one saved field. Generating NEVER records your acceptance — record that with record_case_decision after reviewing the result.

save_discovery_notes#

Write. Save discovery notes on a case, guarded by the exact notes and inputs revision you read — a stale base is refused. Notes are saved verbatim. Pass extract:true with an idempotencyKey to generate a reviewable numeric/evidence proposal; numbers are NEVER applied until apply_case_proposal.

record_case_decision#

Write. Record a typed review decision after you actually reviewed: account-context/profile/discovery kinds, drivers_reviewed / inputs_reviewed / pricing_reviewed (name the BCVD ids for drivers_reviewed), or copy_reviewed. finding_disputed disputes a blocking check finding that does not hold for this case (finalize_case_build names it as blocking_finding_unresolved:<id> or blocking_input_finding:<id>): name the finding ids in targetIds and say why in rationale, which is recorded on the case. A quick-check finding (d-…) also names the current snapshotId and calculationVersion from get_case_results. After no_discovery_available, d-nodiscovery stays blocking until it is disputed; never tag an input CUSTOMER_PROVIDED to clear it. Structural findings cannot be disputed. Evidence references may point to existing Serre records; the actor, gate outcome and content fingerprint are server-derived.

create_business_case#

Write. Create a draft business case for an account (guided): attaches exactly the solutions and drivers you name, calculates nothing, charges nothing — an honest incomplete draft. Prefer plan_business_case + start_case_build, which show the user a plan first.

execute_case_plan#

Write. Run a plan_business_case token through the guided build (start/resume): creates the account if the plan said so, then the draft case with exactly the plan's selection — no calculation, no charge at draft time. Only call this after the user confirmed the plan.

set_case_solutions#

Write. Replace the case's selected solutions. Affected default drivers and default pricing reviews go stale; explicit input and pricing overrides are kept. Seller or account identity cannot change here — start a new plan for that.

create_driver#

Write. Author a driver with a pinned formula. destination: case (the default) authors a case-local driver from businessCaseId + expectedInputsRevision + expression + variables and never creates reusable library content. destination: library publishes a reusable tenant-owned driver naming vendorProfileId + solutionId with calculationLogic {expression, variables}; it does not attach to a case, authorize community contribution or edit an existing library record. Name the driver by id for later patches — duplicate display names cannot target a write.

add_driver_to_case#

Write. Attach an existing seller-owned library driver by valueDriverId, pinning the formula this case sees. Community-shared calculations are retired from business cases: sharedCalculationId is no longer accepted. Repeating the call is idempotent; a previously removed instance is restored rather than duplicated.

remove_driver_from_case#

Write. Soft-remove a case driver by its BCVD id. History remains; the parent library driver is unchanged. Repeat calls on an already-removed id are idempotent.

set_driver_inputs#

Write. Patch known driver or shared/global input keys only. Other keys and drivers are untouched. Valid zero is a value, not an absence. Optional quote, confidence and estimate provenance are recorded with the authenticated actor and acceptance time.

set_pricing#

Write. Save explicit investment components plus term and discount. Per-seat quotes are composed server-side: pricePerSeat × seats × 12 for monthly billing, or × seats for annual billing. annualSubscription is an already-composed yearly total. Benefits-only requires presentationMode BENEFITS_ONLY plus rationale recorded later via record_case_decision.

run_inputs_check#

Write. Run the deterministic inputs check on saved effective state only — never on caller-supplied check data. Structural formula and ownership errors cannot be waived. Returns the recorded findings and updated gates.

propose_case_copy#

Write. Save caller-authored wording for this case (title, driver labels, narrative, impact cards, private glossary) without applying it. Free: no model call and no credit. Supply current case/copy/language revisions and, for any calculation-derived claim, the exact snapshot id/version/hash/mode. Does not publish.

calculate_case#

Write. Run the ROI engine on the saved case and freeze a snapshot. All before-calculate gates must pass. Zero AI credits; a case credit is charged only on the first stamp. Does not mint a public link and does not complete the build. After a successful stamp, run run_quick_check if the free check did not persist, then review the numbers and finalize.

run_quick_check#

Write. Free deterministic review of one exact persisted snapshot. Never recomputes numbers, never consumes a case credit or AI credit, and never mints a public link. Retry this when calculation succeeded but the automatic check failed. Name the current snapshotId, calculationVersion and buildFingerprint (get_case_results returns them under snapshot).

finalize_case_build#

Write. Issue the immutable private completion receipt after every required gate passes. Free; no model call, no public token. Names the current content revision and either a standing output_reviewed decision id or a rationale that records one against the current snapshot. Optional Val Review is not required.

generate_business_case#

Write. Guarded alias of calculate_case (SER-1323 M4): runs the engine under the same pre-calculation gates and credit rules. Does not complete the case, does not share it, and does not consume an AI credit. Prefer calculate_case. Supply the current inputsRevision and contentRevision.

suggest_inputs#

Write. Generate reviewable numeric starting assumptions for the case's current pinned formulas and buyer context. Persists a proposal only — it does not write account fields or case values. Apply a selected subset with apply_case_proposal.

suggest_drivers#

Write. Deal-aware driver candidates from the case's buyer context and selected seller mechanisms. Returns fit/omission/overlap rationale. Does not attach drivers.

apply_case_proposal#

Write. Apply a selected subset of a persisted proposal. Numeric and discovery kinds use exact BCVD/key targets. Copy proposals use kind case_copy with change ids. A successful subset consumes the proposal; retry returns the stored result.

No arguments.

run_val_review#

Write. Optional paid Val Review of the CURRENT snapshot and context (up to 2 AI credits, including account-condition assessment). Prior reviews remain historical/stale; this never blocks calculation or completion. Paid review is not a readiness gate.

confirm_review_finding#

Write. Explicitly accept or reject one CURRENT Val Review finding. Accepting a proposed numeric change really applies it (build permission required). A comment-only reviewer cannot mutate. An old review instance cannot apply a newer slot. The HTTP confirm beacon remains audit-only and does not apply values.

generate_buyer_brief#

Write. Generate an account-level buyer brief (1 AI credit). This is NOT a case deliverable narrative, NOT a readiness gate, and NOT Val Review. Distinct from generate_business_case / case narrative.

share_case#

Write. Explicitly mint or refresh a buyer share link. Separate from completion: no public link unless the user requested sharing. Checks live share permission, SHAREABLE_LINK entitlement, current completion receipt and configured human approval. Token mint/refresh and the delivered-copy stamp run in one revision-guarded transaction. Replay rechecks revoked permissions, a stale receipt, and expired/revoked tokens — stored idempotency cannot resurrect a revoked link. Revoking the API key does not itself revoke existing share links; revoke the case share to take a live URL down. Private apply/generation/finalize never advance the delivered copy pointer.

create_company_profile#

Write. Create a seller/company profile (guided): the company's own identity, classification (industry from the fixed list, sub-industry from that industry's bucket), who it sells to (segments, target industries, buyer and user personas), value focus, sizing, narrative and proof highlights. The first profile in a workspace becomes the default. Refused when a profile with that name exists, or when first-run setup already started a placeholder profile — update that one instead. Returns the profile id and contentRevision every later write on it presents.

update_company_profile#

Write. Correct or extend one company profile's fields (guided): a true partial — only the fields you send change; null clears a scalar, an empty list clears a list. Supply the contentRevision you read; a stale one is refused with the live revision so a teammate's edit is never overwritten. Company fields describe the seller; manage buyer roles with personas and product/value/pricing details on solutions; a sub-industry must belong to the industry the save leaves in place.

add_evidence#

Write. Add an evidence item (case study, analyst quote, internal benchmark or third-party study) to a company profile's library and link it to the library drivers it backs. Evidence is company-profile content: pass the contentRevision you read and a stale one is refused. The source URL is stored as a link, never fetched.

update_evidence#

Write. Edit an evidence item's title, summary, key metric or source URL. A field an approved connection cites is covered by its approval fingerprint, so editing it deliberately retires that approval — it is never silently re-approved. Pass the owning company profile's contentRevision; a stale one is refused.

create_solution#

Write. Create a solution (a product or service the company sells) on a company profile: name, description, classification by taxonomy slug (read list_solution_taxonomy), value story (mechanism, differentiator, anti-claims), pricing model and tiers. The first solution created on a profile becomes its flagship, the one first-run setup and the value model are written about; isFlagship in the result says whether this one is. Pass the profile's contentRevision; a stale one is refused. Returns the solution id, the new contentRevision and its completeness gaps.

update_solution#

Write. Correct or extend one solution's fields — a true partial: only the fields you send change, null clears. Covers name, description, classification, value story, type, target industries and pricing. Pass the company profile's contentRevision (from get_solution); a stale one is refused. Formulas of linked drivers are not edited here.

link_solution_driver#

Write. Link existing library value drivers (by id, from list_value_drivers or create_driver with destination: library) to a solution, idempotently — already-linked ids are reported, not duplicated. Drivers must belong to the solution's company profile. A link is company-profile content: pass the contentRevision you read; a stale one is refused.

unlink_solution_driver#

Write. Unlink one library driver from a solution. The driver itself stays in the library and past business cases keep their frozen numbers. Idempotent; pass the contentRevision you read and a stale one is refused.

create_persona#

Write. Add a buying-committee persona (a role, never a person) to the workspace's persona library: a job title, an optional deal role, and optional research context. Titles collapse to one seat key — a spelling variant of an existing persona is refused and names it; re-creating a deleted persona's title revives it. Multiple personas can share a deal role, including economic buyer. Returns the persona id and revision update_persona presents; research_persona fills the profile fields.

update_persona#

Write. Correct or extend one persona: title (re-keyed; a collision with another seat is refused), deal role, research context, or the researched profile fields (day in the life, pain points with urgency, KPIs, objections with frequency, language patterns, political dynamics). A hand-set profile field is marked as the seller's until the next research run. Supply the revision you read; a stale one is refused with the live revision.

research_company_profile#

Write. Research a company from its website as a durable job: reads the site, extracts a draft profile (identity, industry, market, narrative, highlights, detected solutions) and settles it for review. Nothing is written to the profile — poll get_ai_job with the returned jobId until terminal, then write what you accept with create_company_profile / update_company_profile / create_solution. Consumes 1 AI credit on success; a failed job charges nothing.

research_solution#

Write. Research one solution from its product page: generates its value story (mechanism, differentiator). With applyValueStory the value story is written onto the solution; otherwise it is returned as a draft to apply with update_solution. Consumes 1 AI credit on success and nothing on failure; a quota stop is reported, not thrown.

research_persona#

Write. Research one persona and write its six profile fields (day in the life, pain points, KPIs, objections, language patterns, political dynamics) onto the record, overwriting all six — hand edits are replaced. Uses the persona's research context, else the company's target market. Consumes 1 AI credit on success and nothing on failure; the persona's revision advances, so read list_personas again before the next update.

start_value_capture#

Write. Start a value capture for one product from the material you name (up to 3 public pages or pasted texts): records the request and creates a private draft — no model work yet, nothing charged. The capture is the only way claims, mechanisms, capabilities, conditions and evidence requirements enter the library. Call advance_value_capture to run it; the same idempotencyKey with the same material returns the same run.

advance_value_capture#

Write. Run the next stage of a value capture (collect → extract → measured outcomes for tagged case studies → synthesize → settle). Each call advances one fenced stage and returns; call again until status is ready, then get_value_capture for the proposal and its apply preconditions. The run bills at most 1 AI credit in total; a stage that fails charges nothing and can be retried.

review_value_capture#

Write. Record a review of a ready capture's proposal, item by item: accept, exclude, defer, or correct an item's text. Nothing reaches the library until apply_value_capture. Both the run revision and the draft revision you read are presented; a stale one is refused.

apply_value_capture#

Write. Apply a reviewed value capture to a solution: mints or updates the canonical claims, capabilities, conditions and evidence requirements from the exact draft you reviewed, attaching the capture to the solution. The intent presents the run, draft and source fingerprints you read, so a draft that moved is refused. Goes through the solution save, so the company profile's contentRevision is claimed too. activation: library_only keeps claims proposed; approve also approves them.

approve_value_claim#

Write. Approve one value claim bundle exactly as you read it: the claim version, its fingerprint and each cited relation's revision and fingerprint (the review object from get_solution). A bundle that moved since is refused. Requires the approve permission; the approval is recorded against the key's owner.

create_benchmark#

Write. Propose a tenant benchmark from a source artifact and verbatim quote. Read the source version first and pass expectedSourceVersion; stale sources are refused. operationKey makes retries idempotent. Creates the source SUPPORTS proof atomically. Always proposed; a Reviewer must approve before it can be used in a case. The same metric, value and unit from the same source is refused as a duplicate that names the existing benchmark.

complete_onboarding#

Write. Complete first-run setup for a company profile once every required readiness gate passes (a named company, a classified solution, a driver linked to the flagship) — the same receipt the app's review step records, so the workspace opens for its members. Open required gates are returned, never bypassed; the drivers gate may be waived with a rationale. Completion also needs a usable value model (a flagship with its value mechanism, an approved business-case claim, a driver whose formula evaluates); unmet items come back as valueModel with the step that closes each. Runs no AI and charges nothing. Idempotent on a completed profile.

start_library_agent#

Write. Start a durable library proposal tool loop from a settled measured-outcome capture. Citation metadata must be seller-confirmed. Nothing activates automatically. 1 AI credit per run plus 1 per admitted new driver; use advance_library_agent to continue.

get_library_agent#

Read. Read the library agent's saved actions, refusals, source quotes, proposed content and exact review fingerprint. Only the owned tenant run is readable.

advance_library_agent#

Write. Continue one saved library tool-loop checkpoint. The same read_library, propose_driver, propose_benchmark, propose_relation, attach_evidence and propose_claim_link registry tools execute as the app, with gates fed back for correction. Call until stage is done; replay duplicates nothing.

review_library_agent#

Write. Explicitly approve or reject listed library proposals after reading their content. Requires Reviewer authority, exact run revision and manifest fingerprint; omit itemIds to review all pending proposals. Rejection activates and links nothing.

Errors#

A call can fail at the transport, protocol or tool boundary:

• An HTTP error rejects invalid origins (403), oversized bodies (413) or request limits (429 with Retry-After).
• A protocol error (error on the JSON-RPC envelope) means the request itself was wrong: an unknown tool, a method the server does not have, a missing key.
• A tool failure (result.isError: true with a message in content) means the tool ran and could not do what was asked, such as invalid arguments or an unavailable record. The message is written for the assistant to read back and act on.

Limits#

All requests, including initialization and tool lists, are capped per key and workspace per minute before body parsing. Limit responses return HTTP 429 with Retry-After. The available read tools consume no AI generations. Request bodies are limited to 64 KiB.