/**
 * Tool-description composition.
 *
 * A tool description is read by a model that has never seen this API, in a
 * `tools/list` payload holding 181 siblings. What it has to answer, in order:
 * *what does this do*, *should I call it or a neighbour*, *what will happen*,
 * *what comes back*. Nothing else earns its bytes — a paraphrase of a schema
 * the client already received costs context and buys nothing, so the builders
 * below never restate `.describe()`-d parameters. The one exception is
 * search-filter guidance, where the *vocabulary* (which of `states` /
 * `candidateStates` / `resourceStates` this endpoint accepts) is the whole
 * difficulty and lives per-endpoint in `src/schemas/index.ts`.
 *
 * Why a builder rather than 182 hand-written strings: the weak half of the
 * catalogue is the reference/admin domains, which are registered through
 * `crud-factory.ts` and therefore share five templates. Fixing the templates
 * fixes ~120 tools at once and keeps them consistent, which is exactly what a
 * model needs to tell siblings apart. The facts that MUST NOT drift
 * (pagination ceilings, `fields` semantics) are interpolated from
 * `constants.ts`, not retyped — the previous hand-written template announced
 * `pageSize (défaut: 20, max: 100)` against a schema enforcing
 * 30/500 and shipped that contradiction to 11 domains.
 */
export interface ToolDescriptionSpec {
    /**
     * Front-loaded purpose: verb + resource + scope, one sentence. This is the
     * only part guaranteed to be read when the catalogue is long, so it must be
     * enough to shortlist or discard the tool on its own.
     */
    purpose: string;
    /** When this tool is the right call. */
    when?: string;
    /**
     * When it is NOT, naming the tool to use instead. Omit only for a tool with
     * genuinely no neighbour — a vague "see other tools" is worse than silence.
     */
    instead?: string;
    /**
     * Behaviour a caller cannot infer from the schema or the annotations:
     * side effects, replace-vs-merge semantics, server-side clamping,
     * confirmation prompts, silently ignored fields.
     */
    behaviour?: string[];
    /** Endpoint-specific filter vocabulary / usage detail (search tools). */
    details?: string;
    /** What the call returns, in the shape the caller will actually receive. */
    returns: string;
}
/**
 * Render a spec into the catalogue's uniform layout. Sections are omitted when
 * empty rather than emitted blank, so a two-line reference tool stays two
 * lines.
 */
export declare function composeDescription(spec: ToolDescriptionSpec): string;
/**
 * The pagination contract, worded from `constants.ts`. `page` is capped rather
 * than clamped — the schema *rejects* a higher page so the model refines its
 * filters instead of walking 50 000 records (see `MAX_SEARCH_PAGE`).
 */
export declare const PAGINATION_DISCLOSURE: string;
/**
 * The opposite contract, for the reference routes that accept `maxResults` and
 * discard it (see `TOOLS_IGNORING_PAGINATION`, measured against the live API).
 * Says the two things a caller acts on: asking for fewer rows changes nothing,
 * and there is no second page to fetch.
 *
 * Stating the ceiling on these tools would be the same defect the catalogue
 * just removed — a description promising behaviour the endpoint does not have.
 */
export declare const PAGINATION_INERT_DISCLOSURE: string;
/**
 * `fields` is the catalogue's main token-economy lever and is invisible in the
 * schema alone: the name list is applied *client-side* to the response, is
 * never forwarded to BoondManager, and silently ignores names the entity does
 * not carry. A model that does not know this either never uses it or expects
 * it to filter server-side.
 *
 * Kept deliberately terse. `SERVER_INSTRUCTIONS` already states the rule once
 * for the whole session, and this repeats it on 32 tools — a duplication the
 * project otherwise avoids on purpose (see `fieldsField` in
 * `src/schemas/index.ts`, terse for the same reason). It is here because a
 * tool-definition scorer, and a client that lists tools without ever reading
 * `instructions`, both see the tool in isolation; every word is therefore paid
 * 32 times, so it stays at the shortest form that still says *client-side*,
 * *never sent*, and *silently ignored*.
 */
export declare const FIELDS_DISCLOSURE: string;
export interface EntityWording {
    /** Singular, lowercase — "candidat", "compte utilisateur". */
    entityName: string;
    /** Plural, lowercase — "candidats", "comptes utilisateurs". */
    entityNamePlural: string;
    /** Tool-name prefix — "boond_candidates". */
    prefix: string;
}
/**
 * Default search description for a reference/admin domain: no endpoint-specific
 * filter vocabulary, so the value it adds over the schema is the pointer to the
 * matching `_get` and the shape of what comes back.
 *
 * It deliberately does **not** state the pagination or `fields` contracts.
 * Those are appended by `withParameterDisclosure`, which is the single source
 * for both — and has to be, because the right pagination sentence depends on
 * the *route*: four reference endpoints accept `maxResults` and discard it
 * (`TOOLS_IGNORING_PAGINATION`), so a template that hard-coded the ceiling
 * would make a promise the endpoint breaks, and would suppress the correct
 * wording by having already mentioned `pageSize`.
 */
export declare function defaultSearchDescription(opts: EntityWording): string;
export declare function defaultGetDescription(opts: EntityWording & {
    withTab: boolean;
}): string;
export declare function defaultCreateDescription(opts: EntityWording): string;
export declare function defaultUpdateDescription(opts: EntityWording): string;
export declare function defaultDeleteDescription(opts: EntityWording): string;
export interface TabDescriptionSpec extends EntityWording {
    /** Human name of the tab's content — "profil technique", "actions". */
    subject: string;
    /** What the tab actually holds, parenthetical-style detail. Omit when the subject already says it. */
    content?: string;
    /** What comes back. */
    returns: string;
    /** Extra behavioural facts, if any. */
    behaviour?: string[];
}
/**
 * Tab tools are the catalogue's biggest disambiguation risk: 48 of them, all
 * taking a bare `id`, all returning "some fields of one entity". The
 * description therefore has to state which slice this one holds *and* that the
 * generic `_get` with `tab` reaches the same data — otherwise a model picks by
 * name similarity.
 */
export declare function tabDescription(spec: TabDescriptionSpec): string;
//# sourceMappingURL=description-builders.d.ts.map