M&A deal flow: ranked targets and buyers, valuations, and specialist partner services.
Scored across 9 tools
Most tools occupy genuinely distinct roles: find_matches (mandate search), get_deal_flow (aggregate market view), find_partner_services (partner offerings), and get_valuation (pricing) each have their own domain, while get_exchange_answer vs reply_to_exchange and publish_manifest vs join_workspace are cleanly split by read/write and declare/join semantics. The only mild risk is that find_matches, get_deal_flow and find_partner_services all start from a 'search/browse the exchange' intent, so an agent must parse the long conditional prose ('prefer a mandate-specific search when...') to choose correctly.
All nine names use snake_case with a leading verb and a clear object: find_matches, find_partner_services, get_deal_flow, get_exchange_answer, get_valuation, join_workspace, progress_candidate, publish_manifest, reply_to_exchange. The verb set (find/get/join/progress/publish/reply_to) is small and used predictably, so the pattern is easy to extrapolate.
Nine tools is well within a comfortable range and each maps to a distinct step in the exchange lifecycle (declare, match, value, engage, join, read/reply). Nothing looks padded or redundant.
The surface covers the core lifecycle: publish/re-declare a manifest, validate scope, search matches and partner services, view deal flow, value a company, raise an engagement, join a workspace, and read/reply on the thread. Gaps are minor but real: no way to withdraw or cancel a declaration or an engagement request, no listing of one's own mandates/workspaces apart from reading a known msgid, and no tool for the referenced disclosure/NDA stage or for retrieving detail on a single matched counterparty.
Use this when the user wants to find companies to acquire, buyers or investors for a business they may sell, or counterparties matching a stated mandate — by sector, geography, size or business model, in technology or software. Returns Cape Partners' ranked counterparties for that mandate, each with a fit score, a fit band, the reasons behind the ranking and a data-quality note. Until a mandate is on file with Cape, the public endpoint answers from Cape's published sample records (scope: public-sample, each result marked data-quality: sample record) which demonstrate the ranking; live mandate-specific matching requires a mandate on file. Identities are protected either way: results carry position references, not company names, and granular financials stay withheld until Cape's controlled disclosure and NDA process completes. This tool does not contact anyone and does not create a relationship. Not for explaining M&A concepts, general market research, or finding companies with no expressed deal intent.
| Name | Required | Description | Default |
|---|---|---|---|
| sector | No | Sector or sub-sector the user named, if any. | |
| mandate | Yes | What the user wants to buy or sell, in their own words. Include the sector, geography, size and business model they actually stated; do not add criteria they did not give. | |
| geography | No | Country or region the user named, if any. | |
| counterparty_role | No | Which side of the deal the user needs to find. Use 'any' when unclear. |
| Name | Required | Description |
|---|---|---|
| book | Yes | |
| scope | Yes | |
| matches | Yes | |
| identity_note | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint/openWorldHint/non-destructive, and the description adds substantial context beyond them: sample-vs-live data paths keyed to mandate presence, per-result data-quality flags, identity masking via position references, withholding of granular financials until controlled disclosure and NDA, and the explicit statement that it contacts no one and creates no relationship. That last claim is consistent with readOnlyHint rather than contradicting it.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loads the trigger conditions, then data/identity behavior, then exclusions — a sensible order with no filler sentences. It is on the long side and the return-value inventory (fit score, band, reasons, data-quality note) partially duplicates the existing output schema.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists, yet the description still supplies what the schema cannot: the sampling/identity-protection regime and the mandate-on-file prerequisite. For a tool with 4 params, one enum, and a nominal read-only profile, nothing an agent needs in order to call it correctly or set user expectations is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and each parameter already carries a description, so the schema does the heavy lifting. The description restates the filter axes (sector, geography, size, business model) and the 'do not add criteria' constraint, which mirrors the mandate field's schema text rather than adding new meaning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource plus the multiple framings of the same task ('find companies to acquire, buyers or investors for a business they may sell, or counterparties matching a stated mandate'), and narrows scope to 'technology or software'. An agent can tell this apart from siblings like get_valuation or get_deal_flow without opening their schemas.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives explicit when-to-use conditions and an explicit exclusion list ('Not for explaining M&A concepts, general market research, or finding companies with no expressed deal intent'). It also names the prerequisite that governs which data path runs: live mandate-specific matching requires a mandate on file, otherwise the public sample endpoint answers.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Use this whenever the user needs a business service, specialist, consultant, AI agent or capability that a partner organisation may provide through the Cape Agent Exchange — including outside M&A. Do not assume the exchange is M&A-only. Queries the exchange's live service vocabulary and the offerings registered with Cape by enrolled partners, returning each offering with the vertical that declares it and its effect constraints (whether it is proposal-only or requires a human gate). This is search only: it cannot contact a partner, request a quote or start an engagement. It also returns capability_tokens: the exact spellings this exchange READS for a mandate's scope.capability — write one of those there rather than a sentence, so the mandate can be COUNTED instead of only read. If nothing registered matches, say so plainly rather than suggesting a general provider.
| Name | Required | Description | Default |
|---|---|---|---|
| need | Yes | The capability the user needs, in their own words. Include the outcome they want, not just a job title. | |
| vertical | No | Only if the user named a specific provider category. |
| Name | Required | Description |
|---|---|---|
| book | Yes | |
| note | Yes | |
| next_step | Yes | How a declared offering becomes a named introduction: the need goes on file, then the human gate. |
| offerings | Yes | |
| vocabulary | Yes | |
| capability_tokens | Yes | The capability spellings a mandate scope can be matched on — write one as `scope.capability`, not a sentence. |
| capability_tokens_shown | No | How many spellings THIS list carries. |
| capability_tokens_total | No | How many spellings the whole catalogue holds. |
| capability_tokens_truncated | No | True when this list is a PARTIAL view of the catalogue — never read it as the whole vocabulary. |
| capability_tokens_family_cut | No | True when the 60-item cap cut the family this list belongs to; name one spelling to get that family whole. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnly, openWorld, and non-destructive annotations, the description explains that it queries live vocabulary and registered offerings, returns the declaring vertical and effect constraints such as proposal-only or human-gate requirements, and surfaces capability_tokens for mandate scope.capability. It also discloses search-only boundaries and no-match behavior, which is substantial behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the primary use case and then adds important constraints, fallback behavior, and return-value context. It is dense and mostly earns its length, though a few sentences could be tightened without losing meaning.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that an output schema exists, the description need not enumerate every return field, but it still explains the key return facets: offerings, their declaring vertical, effect constraints, and capability_tokens. It also covers search-only limits and the no-match case, leaving no material gap for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the input schema already documents the two parameters and the baseline is 3. The description adds some contextual meaning about capability vocabulary and vertical selection, but it does not add syntax or format details for the `need` and `vertical` parameters beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: it queries the Cape Agent Exchange's live service vocabulary and registered partner offerings for a needed business service, specialist, consultant, AI agent, or capability. It also clearly distinguishes this as a search-only tool, so an agent can understand its scope without opening the schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives explicit when-to-use guidance ('Use this whenever the user needs a business service...') and clarifies a common misconception by saying not to assume the exchange is M&A-only. It also states what the tool cannot do — contact a partner, request a quote, or start an engagement — and advises saying so plainly if nothing matches, though it does not explicitly name sibling alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Use this when the user wants to see what is available rather than search for one specific mandate — the shape of the market, how many companies are qualified, or which sectors and geographies are represented. Returns Cape Partners' broader scored deal universe as aggregate counts by sector, with size bands and the best fit achieved in each: no company names and no individual records. Prefer a mandate-specific search when the user has one in mind.
| Name | Required | Description | Default |
|---|---|---|---|
| focus | No | What the user wants an overview of, in their own words. | |
| limit | No | Maximum sector rows to return. Default 20. | |
| sector | No | Sector or sub-sector the user named, if any. | |
| geography | No | Country or region the user named, if any. |
| Name | Required | Description |
|---|---|---|
| book | Yes | |
| note | No | |
| scope | Yes | |
| counts | Yes | |
| sectors | Yes | |
| next_step | Yes | What to do with the counts: how a mandate on file turns orientation into a ranked, named shortlist. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare read-only, non-destructive and open-world, so safety is covered. The description adds genuinely new behavioral context the annotations cannot convey: results are aggregate only, contain no company names or individual records, and include size bands plus best-fit per sector. It stops short of covering pagination or ordering of the sector rows.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the usage trigger followed by the return shape, with no filler. The middle clause listing 'shape of the market, how many companies are qualified, or which sectors and geographies' is slightly enumerative but each example maps to a real use case.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists, so return values needn't be explained, yet the description still summarizes that output as aggregates rather than records — the most decision-relevant fact. Combined with clear usage routing and zero required parameters, an agent has what it needs; only pagination/limit behavior is left implicit.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so each parameter (focus, limit, sector, geography) is already documented in the schema, and the description adds no syntax, format, or defaulting detail beyond it. Baseline 3 applies; it does implicitly confirm sector and geography are the axes being aggregated, but that is marginal.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb ('see what is available') plus resource ('Cape Partners' broader scored deal universe') and pins the output shape: aggregate counts by sector with size bands and best fit. It explicitly contrasts with mandate-specific searching, so an agent can distinguish it from find_matches without opening either schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives a clear condition for use ('when the user wants to see what is available rather than search for one specific mandate') and an explicit exclusion with the alternative ('Prefer a mandate-specific search when the user has one in mind'). No inference required.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Use this to read your own thread on the Cape exchange: what was answered, plus your state (tier, handshake, scopes, pairings) and the scope verdict on your manifest. Needs the key (msgid) from a previous publish_manifest — the caller already holds it. Read-only.
| Name | Required | Description | Default |
|---|---|---|---|
| key | Yes | Your msgid (or answer key). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered; the description adds real value by disclosing the response contents (thread answer, state dimensions, manifest verdict) and the caller's existing possession of the key. It does not cover pagination, staleness, or error behavior, but those are minor for a single-key read.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the purpose before the parenthetical inventory of returned state and the prerequisite. The trailing 'Read-only.' duplicates readOnlyHint, and the parenthetical list is dense, but virtually every clause carries information the agent needs to call it correctly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description carries the burden of describing returns, and it does so at a useful level of granularity (answer, state fields, manifest verdict) for a one-parameter read. Enough is present to call the tool and interpret its response; only edge-case behavior (missing/expired key, empty thread) is unspecified.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the single param is already described as msgid/answer key, so baseline would be 3. The description earns a point by adding provenance the schema lacks: the key must come from a prior publish_manifest and the caller already holds it, which tells the agent where to source the value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (read) and a specific resource (your own thread on the Cape exchange), then enumerates exactly what comes back: the answer, your state (tier, handshake, scopes, pairings), and the scope verdict on your manifest. An agent can distinguish it from publish_manifest (which produces the key) and reply_to_exchange (which writes) without opening a schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Clear usage context: it is the read step that follows a publish_manifest, and the prerequisite ('Needs the key (msgid) from a previous publish_manifest') is spelled out. It stops short of naming the sibling it substitutes for in a read/write pair (reply_to_exchange) or stating when not to call it, so it is strong but not exhaustive.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Use this when the user asks what a company is worth, wants a valuation range, or is preparing to buy or sell and needs an indicative number. Returns Cape Partners' indicative valuation range, produced by its triangulated method — revenue multiple, EBITDA multiple, discounted cash flow, a conservative floor and a weighted triangulation — together with the method used, the assumptions it rests on and a data-quality note. It is indicative and non-binding: not an offer, an appraisal or investment advice, and it commits neither Cape nor any counterparty. Use the financials the user provides; do not estimate figures they did not give, and say so plainly if the range depends on assumptions you supplied.
| Name | Required | Description | Default |
|---|---|---|---|
| sector | No | Sector the user named, if any. | |
| company | Yes | What the user told you about the company, in their words. | |
| nrr_pct | No | Net revenue retention as a fraction (1.15 = 115%); 115 is also accepted. Software/hybrid only. Only if the user stated it — never estimate it. | |
| geography | No | Country or region the user named, if any. | |
| growth_rate | No | Annual growth. 0.3 or 30 both mean 30%, only if stated. | |
| revenue_eur | No | Revenue in euros, only if the user stated it. A string like "8M" is accepted. | |
| ebitda_margin | No | EBITDA margin. 0.2 or 20 both mean 20%, only if stated. | |
| business_model | No | The family model to value with, only if the user described the business: software_saas (recurring software), it_services (project or staffed services), hybrid (both). Stored lowercase. | |
| gross_margin_pct | No | Gross margin as a fraction (0.70 = 70%); 70 is also accepted. Only if stated. | |
| top_customer_pct | No | Share of revenue from the largest customer as a fraction (0.25 = 25%); 25 is also accepted. Only if stated. | |
| recurring_share_pct | No | Share of revenue that is recurring. Stored as a fraction (0.65); 65 is also accepted and converted. Only if stated. |
| Name | Required | Description |
|---|---|---|
| book | Yes | |
| model | No | three_method | profitability_unknown | profitability_disciplined. |
| scope | Yes | |
| method | Yes | |
| methods | No | Only the methods that produced a figure; see methods_omitted. |
| weights | No | The weights actually applied, after any redistribution. |
| next_step | Yes | What to do with the figure: how a mandate on file turns an indicative value into a ranked, named shortlist. |
| confidence | No | |
| disclaimer | Yes | |
| assumptions | No | |
| data_quality | No | |
| family_model | No | The family-model view of the same inputs, matching what the web app shows: ev, range_eur, confidence and score with reasons, implied_multiples, benchmark_position, contributions, inputs_echo, k_market and params vintage. null when the family model is off. |
| legacy_engine | No | DEPRECATED. The retired triangulation, kept one release for traceability. Do not quote it: the top-level headline is the family model. |
| qualification | No | What to ASK the user next: the quality fields this answer had to default (nrr, top_customer, gross_margin), what supplying them is worth in confidence points, and the sentence to use. Relay the questions; do not invent the answers. |
| method_sources | No | Where each method figure came from: the multiple, the tier and the premiums, or the DCF parameters. |
| methods_omitted | No | |
| value_range_eur | No | The valuation RANGE, derived from how much is known: the half-width follows the confidence score (+/-15% at a perfect score, +/-22% at the HIGH/MEDIUM boundary, +/-45% at zero), never how far the methods disagree — see method_dispersion_eur. null when Cape abstains. |
| triangulated_eur | No | |
| valuation_status | No | abstained = Cape declines to provide a valuation; this is not a valuation of zero. |
| abstention_reason | No | |
| confidence_reasons | No | |
| confidence_band_pct | No | Half-width of the returned range as a fraction of the headline (0.15 = +/-15%), so it always agrees with value_range_eur. |
| method_dispersion_eur | No | min/max across the methods that produced a figure. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only establish that this is a safe read; the description goes well beyond by disclosing what comes back (range, method, assumptions, data-quality note) and the legal character of the output (non-binding, not an offer, appraisal, or investment advice). It also adds an operational constraint not present in the annotations: do not estimate figures the user did not supply, and flag dependence on supplied assumptions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loads the trigger condition, then the return contents, then the caveats and the no-fabrication rule — a sensible order. It is somewhat long and the disclaimer clause is dense, but each sentence contributes a distinct constraint rather than padding.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For an 11-parameter analytical tool with a full schema and an output schema, the description supplies everything the agent still needs: when to call it, the nature and limits of the output, and the rule against inventing inputs. Nothing material is left to inference.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with per-field notes on formats, fractions vs percentages, and the software-only restriction on nrr_pct, so the schema carries the parameter burden. The description's one added rule — use only user-provided financials and never estimate — largely restates what fields like nrr_pct already say ('never estimate it'), so it adds little beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('returns Cape Partners' indicative valuation range') and enumerates the methods behind it (revenue multiple, EBITDA multiple, DCF, floor, weighted triangulation). No sibling tool overlaps this function, so an agent can select it without ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives concrete triggering conditions: user asks what a company is worth, wants a range, or is preparing to buy or sell. It also bounds scope by declaring the result indicative and non-binding. It stops short of naming when-not-to-use cases or pointing to a sibling alternative, which keeps it at 4 rather than 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Use this ONLY after a manifest has been ACCEPTED and the user wants the workspace that follows the handshake. Requires the exchange key of that accepted manifest, a NEW uuid for this workspace, and the ACCOUNTABLE HUMAN's own name, business email and company — the endpoint binds a person, and refuses the join without all four. Take those three from the user's own words and never invent them. It never takes over an existing workspace, and a refusal (workspace_not_yours, delegation_entity_mismatch) is reported rather than retried. Joining places the declared organisation in the corpus serving the mandate, marked UNVERIFIED. The call is staged: a dry run sends nothing, and the confirmed call is bound to the exact payload that dry run returned. Call once with dry_run=true to get the exact payload and a confirmation_token; call again with the same arguments plus that token to send. A token that does not match the payload is refused and nothing is sent.
| Name | Required | Description | Default |
|---|---|---|---|
| key | Yes | Exchange key of the ACCEPTED manifest. | |
| name | Yes | The accountable human's name, as the user stated it. Required by the endpoint — never invented. | |
| Yes | The accountable human's BUSINESS email, as stated. Required; consumer mailboxes (gmail, outlook, …) are refused. | ||
| company | Yes | The organisation the workspace is registered for, as the user stated it. Required. | |
| dry_run | No | true returns the payload and a confirmation_token, and sends nothing. | |
| new_uuid | Yes | A new uuid4 for this workspace (36 chars, dashed). Never reuse an existing one. | |
| request_id | Yes | Your own idempotency key for this join. | |
| confirmation_token | No | The token from the dry run, for the confirmed send. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations, it discloses the refusal codes (workspace_not_yours, delegation_entity_mismatch) and that they are reported rather than retried, the fact that the joined organisation is recorded as UNVERIFIED in the mandate-serving corpus, and the staged dry-run/confirmation-token binding with its mismatch rejection. The mutation profile is well covered by destructiveHint=true, and the description adds the side effects and failure modes the annotation cannot express.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Sentences are front-loaded and each carries a distinct rule — gating condition, required identity, refusal behavior, side effect, staging protocol. It is dense and slightly repetitive with the schema on the business-email and never-invent points, but nothing is filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For an eight-parameter, multi-step, irreversible join with no output schema, the description covers everything an agent needs: preconditions, required human-supplied values, the two-phase confirmation flow, side effects, and non-retryable errors. No return-value explanation is needed since the dry run's payload is what the confirmation binds to.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3; the description goes slightly beyond it by framing the name/email/company trio as a person-binding requirement that must come from the user's own words and that the endpoint refuses to join without. It does not add format or validation detail for key, new_uuid, or request_id beyond what the schema already states.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource (join a workspace) and pins the lifecycle state precisely: it only applies after a manifest has been ACCEPTED and the handshake has completed. That implicitly separates it from publish_manifest and get_exchange_answer, but no sibling tool is named explicitly, so it falls short of full sibling differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives an explicit gating condition ("Use this ONLY after a manifest has been ACCEPTED"), an exclusion ("It never takes over an existing workspace"), and an exact two-call procedure with dry_run=true first and the confirmation_token second. It also warns against retrying refusals and against inventing identity values, which is the kind of when-not guidance most tools omit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Use this when the user wants to ACT on a counterparty the exchange has already shown them: it raises a supervised ENGAGEMENT REQUEST for that candidate — the introduction — which is the step that turns a match into a conversation, and which nothing else in this app can take. The candidate must be the exact name of one counterparty from the list the exchange handed THIS participant, read back with get_exchange_answer; the exchange validates it against its live list and refuses anything else, so never invent a name and never name a firm found elsewhere. It raises a request: it does not select, award or commit. The call is staged: a dry run sends nothing, and the confirmed call is bound to the exact payload that dry run returned. Call once with dry_run=true to get the exact payload and a confirmation_token; call again with the same arguments plus that token to send. A token that does not match the payload is refused and nothing is sent.
| Name | Required | Description | Default |
|---|---|---|---|
| key | Yes | The msgid / answer key of your accepted declaration. | |
| note | No | Optional note in the user's own words, passed to the desk. | |
| dry_run | No | true returns the payload and a confirmation_token, and raises nothing. | |
| candidate | Yes | The EXACT name of one candidate the exchange handed you. Never invented, never a name from elsewhere. | |
| request_id | Yes | Your own idempotency key for this request. | |
| confirmation_token | No | The token from the dry run, for the confirmed send. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Goes well beyond the annotations by disclosing server-side validation of the candidate against a live list, refusal of unknown names, and the two-phase staged call where a mismatched token sends nothing. It does not, however, say whether a raised request can be withdrawn or what the confirmed call returns, which matters for a destructiveHint=true mutation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with the action and the prerequisite, and every clause carries information. It is dense with long multi-clause sentences and restates the 'never invent a name' rule already in the schema, which costs some crispness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 6-parameter, no-output-schema mutation, the description covers the trigger, validation, refusal semantics, and the dry-run/confirm protocol. The remaining gap is the outcome of a successful confirmed call — nothing describes what the agent should report back after sending.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3; the description earns more by explaining the causal relationship between parameters — dry_run produces the payload and confirmation_token, and the confirmed call is bound to that exact payload — plus the sourcing rule for 'candidate' and the meaning of 'key' as an accepted declaration.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a concrete verb+resource (raises a supervised engagement request for a candidate) and explicitly scopes it against everything else: 'the step that turns a match into a conversation, and which nothing else in this app can take.' An agent can distinguish it from siblings like find_matches or reply_to_exchange without opening a schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives an explicit trigger ('when the user wants to ACT on a counterparty the exchange has already shown them'), names the upstream dependency (read the name back with get_exchange_answer), and states exclusions ('it does not select, award or commit'). The alternative path for discovery (find_matches) is implied by the 'already shown them' framing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Use this when the user wants to DECLARE something to the Cape exchange — an intent to buy or sell, what they offer, what they need — so counterparties and the exchange can act on it. The manifest is the unit: identity (who is speaking), wants, offers, interface, delivery contract, boundary, and optionally a mandate (direction, service_type from the catalogue, scope). Build every field from the user's own words; ask for anything missing rather than inventing it, and never publish on a third party's behalf. Returns a msgid that is the only route back to the thread. Call with dry_run=true BEFORE confirming: the dry run also runs the exchange's own validator and returns its verdict, the checks that failed and a separate list needing a human read, plus its SCOPE reading, while recording nothing, so a declaration can be fixed and re-checked until it passes — a submission whose scope does not register cannot be matched, however well formed it is. Ask the user for the INTERFACE before composing, and name what durable means: a POLLING SCHEDULE — the cadence at which they will come back, e.g. "polls every 30 minutes" — or an endpoint they run that Cape can call. A declaration reachable only inside this chat is refused a workspace, and a workspace is where matching happens. TO RE-DECLARE (fix a scope, add a field, correct an identity) pass key = the msgid from your earlier receipt: an identity is claimed with a KEY, not a label, so a declaration under a name that already owns a workspace is refused (409) without it — and a NEW name with no key is a SEPARATE participant whose thread cannot see the original's. Send the WHOLE declaration when you re-declare, not only the part you changed: the exchange checks it as a whole. The call is staged: a dry run sends nothing, and the confirmed call is bound to the exact payload that dry run returned. Call once with dry_run=true to get the exact payload and a confirmation_token; call again with the same arguments plus that token to send. A token that does not match the payload is refused and nothing is sent.
| Name | Required | Description | Default |
|---|---|---|---|
| key | No | To CONTINUE as a participant you already are, present the msgid (or answer_key) from that earlier receipt. Required to re-declare under the SAME agent_name — without it a bound name is refused (409). Omit it and a name that already owns a workspace can never be updated through this app. | |
| wants | No | What the user wants, as they stated it. | |
| offers | No | What the user offers, as they stated it. | |
| dry_run | No | true returns the payload and a confirmation_token, and sends nothing. | |
| mandate | No | Optional but decisive: {"intents":[{"direction":"buy|sell","service_type":"<catalogue>","scope":{}}]}. An intent is only read from here. | |
| boundary | No | Enforceable limits: what they refuse, require, or exit on. | |
| identity | Yes | Who is speaking, in the user's words. Required. | |
| interface | No | How to reach them / how they accept contact. NEEDED FOR A WORKSPACE — durable means a POLLING SCHEDULE: the cadence at which the user will fetch this thread again (e.g. "polls every 30 minutes"), or an endpoint they run that Cape can call (https://…). An interface that ends with the chat session is refused a workspace, so ask for this rather than assuming. | |
| agent_name | No | Short identifier for this agent. | |
| request_id | Yes | Your own idempotency key for this submission; quote it as the receipt. | |
| delivery_contract | No | What delivery means for this participant. | |
| confirmation_token | No | The token from the dry run, for the confirmed send. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations (write, destructive, open-world), the description discloses a lot of non-obvious behavior: the staged two-call flow bound to an exact payload, token mismatch refusal with nothing sent, 409 on a name that already owns a workspace without a key, workspace refusal when the interface is chat-only, whole-declaration re-validation, and that a submission whose scope does not register cannot be matched. No contradiction with the destructive/openWorld annotations — publishing is indeed an external write.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The purpose and trigger are front-loaded, but the body is a single dense wall of text with CAPS emphasis and several passages that restate the schema verbatim (the polling-schedule/interface explanation, dry_run behavior). Those duplicates cost space that could have been trimmed; the re-declare and token guidance is valuable but buried mid-paragraph.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 12-parameter, nested-object, destructive, open-world tool with no output schema, the description covers the return value (msgid as the only route back to the thread), the dry-run validator output (verdict, failed checks, human-read list, SCOPE reading), and the failure/retry path. Nothing an agent needs in order to call it correctly appears to be missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3, but the prose adds real semantics the schema does not: identity is claimed by KEY not label, the mandate object's intent shape and that intents are only read from there, and the confirmation_token must match the dry-run payload exactly. Some overlap with schema text (interface/polling schedule) reduces marginal value slightly.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description gives a concrete verb and resource ('DECLARE something to the Cape exchange — an intent to buy or sell, what they offer, what they need') and enumerates the manifest's constituent parts (identity, wants, offers, interface, delivery contract, boundary, optional mandate). An agent can tell this is the declaration/creation path as distinct from lookup siblings like find_matches or get_deal_flow, even though no sibling is named explicitly.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It states the triggering condition ('Use this when the user wants to DECLARE...'), prescribes a dry_run-first workflow, and covers the re-declare case with the `key` argument, including the 409 failure mode when a key is missing. The only gap is that it never explicitly contrasts with siblings (e.g., join_workspace or reply_to_exchange) or says when NOT to publish.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Use this to answer on a thread the user already holds, with the key they hold. Send the user's own words: this tool does not compose messages on their behalf, and nothing is sent until they have seen the exact text. The call is staged: a dry run sends nothing, and the confirmed call is bound to the exact payload that dry run returned. Call once with dry_run=true to get the exact payload and a confirmation_token; call again with the same arguments plus that token to send. A token that does not match the payload is refused and nothing is sent.
| Name | Required | Description | Default |
|---|---|---|---|
| key | Yes | The msgid / answer key of the thread. | |
| text | Yes | The reply, in the user's own words. Required. | |
| thread | No | Optional thread label. | |
| dry_run | No | true returns the exact text and a confirmation_token, and sends nothing. | |
| replies_to | No | Optional id of the message being answered. | |
| request_id | Yes | Your own idempotency key for this reply. | |
| confirmation_token | No | The token from the dry run, for the confirmed send. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already flag the call as a non-read, destructive, open-world operation, and the description adds substantial context beyond them. It explains the staged dry-run model, the guarantee that nothing is sent until the user sees the exact text, and the rule that a token not matching the payload is refused, so no message goes out. That is exactly the behavioral disclosure an agent needs before a send.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded: it opens with the verb and resource, then covers the no-composition constraint, then the two-call protocol. Every sentence adds a constraint an agent could otherwise get wrong, and there is no redundant restatement of the name or title.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 7-parameter, non-read tool with no output schema, the description covers the risky part well: the staged send, token binding, and refusal on mismatch. It leaves unclear what the dry-run response contains besides payload and token, but the schema already documents parameter meaning, so this gap is minor.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3; the description goes further and explains how dry_run and confirmation_token work together across two calls, and that the token is bound to the exact payload. It does not clarify request_id idempotency or replies_to beyond what the schema says, but the key non-obvious parameters are covered.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb and resource: it answers a thread the user already holds, using the key they hold, and it explicitly says it will not compose text for the user. It does not, however, distinguish itself from the read-side sibling get_exchange_answer, so an agent must infer the split between reading and replying.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description states the precondition (the user already holds the thread and key) and gives detailed procedural guidance: call once with dry_run=true, then call again with the same arguments plus the token. It still gives no explicit exclusion or alternative to use when the thread is not held or when the agent only needs to read the answer.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
find_matchesfind_partner_servicesget_deal_flowget_exchange_answerget_valuationjoin_workspaceprogress_candidatepublish_manifestreply_to_exchangeFree SME valuation, sell-readiness, M&A pricing, partner and deal-referral tools in EN/FR/ES/PT.
Predictive Signals, Company Search, Sector Trends and Contacts for PEs, IBs, M&A dealmakers.
Find businesses for sale and off-market businesses to buy, with deep dives and a deal pipeline.
OloLand M&A intelligence — 33 tools for deal analysis, valuation, risk, and cross-deal learning.
Add one secure layer between your agents and this server.
