How to prepare a public service catalog for agents

A public catalog gives software agents a predictable way to understand what your business offers. Preparing one is a publishing project: decide which facts are public, make them understandable and keep them current. This guide covers that editorial and testing process. It does not assume you have a private agent platform or authorize agents to act for customers.

1. Choose the authoritative public page

Start with the service page a person would read. Name the person who approves changes to it. A machine-readable record should describe the same offer, with the same limitations, rather than becoming a second place where prices and terms drift apart.

For each service, collect its name, short description, delivery method, prerequisites and ordinary inquiry link. Include a service area only when approved. Include a price only when the currency, basis and conditions are settled. If a field is unknown, omit it or mark its status clearly. An invented zero price is worse than no price.

2. Approve the fields one by one

Create a worksheet with four columns: field, proposed value, public or private, and approving owner. Review examples rather than abstract labels. A business street address may be public; a customer’s home address is not. A general compatibility note may be public; a particular customer’s device serial number is not.

Keep these items outside the public catalog:

• Customer names, appointment details and order history
• Private job notes, uploaded files and support conversations
• Passwords, tokens, internal routes and account identifiers
• Unapproved stock levels, contractual prices or staff schedules

Use a separate publishing dataset containing approved values. Avoid an unrestricted database query followed by an AI instruction to remove private information. Permission checks should determine which information is accessible before a model sees it.

3. Make a small record understandable

Hypothetical example: Cedar Desk Demo publishes a service called “Workspace tool setup.” Its record has a stable ID, a plain-language description, “remote consultation” as the delivery method, a prerequisite to confirm tool compatibility and an inquiry route. The example lists no customers, prices or promised completion time.

The description could read: “Discuss configuration of approved workplace tools. Compatibility and the work included are confirmed before a project begins.” That gives an agent useful boundaries without claiming every app is supported. A field such as “availability: inquiry required” is more honest than a permanent “available now” badge without a scheduling source.

Schema.org’s Service vocabulary includes properties for describing services, providers, offers and areas served. Choose properties that match verified facts; adding structured data does not guarantee discovery by a particular agent. Schema.org Service.

4. Keep discovery read-only

A public catalog endpoint should return intentionally public information. Reading it should never make a booking, take payment, accept terms or change a customer record. An inquiry form is a separate write surface and needs its own validation and abuse handling.

For genuinely public content, keyless access can be appropriate. A key printed on a public page is available to everyone and cannot prove a visitor has permission to see private information. If you use public identifiers for analytics or quotas, label their limited purpose. Never reuse a privileged provider credential. OpenAI’s API-key guidance warns against placing secret keys in browser or mobile client code. API key safety.

5. Give developers a precise contract

Document the endpoint, returned fields, version and error behavior. Include one synthetic response and explain what absent values mean. OpenAPI can describe HTTP operations and security requirements, but the application must implement those checks. A statement in a schema does not make an endpoint safe. OpenAPI specification.

Ask a developer to test unknown IDs, unexpected parameters, overly large requests and repeated requests. Have them confirm that no private fields appear in responses, logs exposed to visitors, cached pages or client bundles. A public endpoint should not gain additional access because a caller supplies a different business ID.

6. Separate future private operations

Customer-specific lookups and actions need their own authentication and authorization. The system must check the caller, business, record and operation. For MCP implementations, the official security guidance discusses token validation, scope minimization and threats such as token passthrough. A public catalog does not establish those controls. MCP security practices.

Explain the distinction to customers: publicly published service information is open to discovery; private records should be accessible only through authorized flows. Neither an obscure URL nor a model’s promise to keep a secret is an access-control system.

7. Plan the next correction

Put the approving owner and review date next to each record in your publishing system. When an offer changes, update the human page and catalog together, then check the response visitors actually receive. Account for caches. Remove retired offers or mark them unambiguously; keep a stable ID from silently changing meaning.

Before launch, ask someone unfamiliar with the business to answer three questions using only the catalog: what is offered, what must be confirmed, and how do I inquire? Bring the worksheet to InstallAI if you want help scoping public discovery separately from private business tools.