Make meaning explicit before adding an interface
Make important information explicit and consistently structured, and document callable capabilities where they are useful, without assuming that access creates recommendation. Machine-readable should mean something more concrete than a label in a proposal. I would ask what information or operation another system needs, how its meaning is represented and what happens when it is used. That keeps technical work connected to the actual task.
“The interface changes. The need for useful decision support does not.”
— Curtiss Witt, The Decision Economy, Chapter 14.
How is machine-readable information different from an operation?
Making information machine-readable means representing it so a system can identify the relevant fields and relationships. It does not mean the system understands every implication or will recommend the business. Begin with the facts and their meaning before choosing a technical format or making a visibility claim.
The public page should make the offer understandable to a person. Hidden metadata should not contain stronger or materially different claims. Treat the human description and machine-readable representation as two expressions of the same source truth, with consistent scope, conditions, and responsibility for updates.
A page can describe a service without providing an operation another system can invoke. Distinguish information about the business from a callable tool. If the goal is to let an agent perform an assessment, a well-structured company description alone does not supply that operation.
State what the operation does, which inputs it accepts, and what result it returns. A name such as “business intelligence” is not a sufficient contract. The client needs enough information to decide whether the tool fits the user’s task and what its output can legitimately establish.
Making information or a tool reachable removes one possible obstacle. It does not determine whether an external system will select it or whether the result is useful. Keep access, selection, invocation, and customer benefit as distinct questions in both the implementation plan and the public explanation.
The comparison below describes two approaches to the work. It is a practical design contrast, not a measured claim that one approach always produces a better commercial outcome.
| Information and activity approach | Decision-support approach |
|---|---|
| Treat every structured file as a callable tool. | Distinguish facts, data shapes and operations. |
| Publish conflicting representations. | Maintain one governed source of meaning. |
| Infer authority from technical access. | Describe effects and authorization separately. |
Which business facts should be organized first?
Identify the organization, offer, author, and tool consistently. Explain their relationships rather than relying on an ambiguous collection of names. Stable labels make information easier to maintain and reduce the chance that a reader or system must guess whether two descriptions refer to the same entity.
Suitability may depend on scope, location, eligibility, or other offer-specific circumstances. State those conditions in the source content before encoding them elsewhere. A structured field containing an incomplete statement can be precisely formatted and still fail to provide the information needed for a responsible decision.
An unknown fact should remain unknown. Do not fill an empty field with a favorable default merely to make the representation look complete. The consumer needs to know when information is unavailable and whether that gap affects use of the offer or tool.
Identify where consequential information comes from and when it was checked or became effective. Provenance helps a consumer understand the basis of a statement. It does not automatically make the statement correct, but it provides a route for inspection and a starting point for maintenance.
Assign a clear home and owner for important facts. Other representations should be updated from that source rather than edited independently without coordination. This makes it easier to correct contradictions and prevents a polished machine-readable copy from continuing to describe an offer that has changed.
Which technical representation serves the task?
Structured data can label entities and relationships within a page. It should reflect visible content and use fields accurately. Do not treat markup as a way to claim credentials, reviews, or outcomes that the page does not support; the representation inherits the same evidence responsibilities. Google Search Central: Introduction to structured data markup; accessed September 2026
A schema can define expected fields, allowed values, and related constraints. It helps a client construct or inspect data, but it does not independently prove that the supplied information is true. A valid answer format and a verified business condition are different claims.
An API can allow a client to request a defined operation and receive a result. The contract should make the input, output, errors, and relevant effects clear. A public URL alone is not enough if the consumer cannot tell how to use it responsibly.
OpenAPI provides a standard way to describe HTTP API capabilities. It is different from an input-only schema or a marketing page about the tool. Use the document to explain how to call the operation, while keeping decision quality and business verification as separate concerns. OpenAPI Specification 3.1.1; accessed September 2026
MCP is a protocol for connecting AI applications with external systems such as tools and data sources. It is one access route, not proof that every assistant will discover or use the capability. Compatibility and task fit still need to be established for the intended client. Model Context Protocol: What is MCP?; accessed September 2026
The working rule I return to is this: “The interface changes. The need for useful decision support does not.” It is a way to judge the next piece of work, while keeping its evidence and limitations visible.
How should permissions and availability be described?
A client should know whether an operation only returns information or changes something. Even a browser tool that updates the current page has an effect worth describing. Do not make the caller infer the consequence from a tool name that sounds informational but behaves more broadly.
A system may be technically able to perform an action without having permission to do it for the user. Describe the supported operation and enforce the relevant authority boundary. Publishing a callable route does not grant every caller unlimited permission to act.
If a feature is implemented but not validated for the intended environment, keep that status explicit. Do not advertise all access routes as interchangeable. Accurate availability information helps clients avoid failed plans and helps the business focus on the specific validation work that remains.
A version should identify a defined contract or ruleset, not simply make the capability look mature. Record changes that affect inputs, output meaning, or behavior. A consumer needs to know when an integration or interpretation should be reviewed because the underlying contract has changed.
When a request cannot be completed, explain the problem within the contract’s scope without leaking sensitive information. A client should be able to distinguish invalid input, unavailable capability, and other meaningful conditions. Silent ambiguity encourages guessing and makes integration failures harder to diagnose responsibly.
How do these layers appear at the Institute?
The Institute’s capability manifest identifies DERA’s purpose, evidence scope, supported routes, and limitations. It is a declaration of the capability, not an independent audit of every condition it describes. Use it as a starting point for a client’s integration and verification work. Decision Economy Institute: live capability manifest; accessed September 2026
The Institute publishes an input/output schema route and a full OpenAPI document at different URLs. They serve related but distinct purposes. Do not label the schema endpoint as the complete OpenAPI description merely because both documents concern the same assessment capability. Decision Economy Institute: live capability manifest; accessed September 2026
Calling DERA through a machine route does not change its evidence basis. The result is BY YOUR ACCOUNT and uses owner-supplied answers. Technical access must preserve that meaning rather than imply that a server response independently observed or certified the business. Decision Economy Institute: live capability manifest; accessed September 2026
Identify one supported operation and verify its documented behavior with appropriate non-sensitive inputs. Check the meaning of the result as well as the response. This provides bounded evidence of the integration without claiming universal compatibility or performing unrelated actions on behalf of the user.
If the facts are unclear, fix the content. If the useful operation lacks a contract, document it. If the intended client cannot connect, test that route. This separates distinct tasks and avoids buying a broad “machine-ready” label without knowing which customer problem the work solves.
What can I do with this today?
Start with one offer and write down the next decision this article helps you examine. Give the work a defined scope before adding a new page, tool or integration.
1. Separate content cleanup from interface engineering.
2. Identify the consequential fact or condition that remains uncertain. Name who can check it and what would establish completion.
3. If you need help ordering the business work, complete the free Decision Economy Readiness Assessment. Read its reasons and three starting actions, then choose the first task you can inspect.
Our own example is deliberately bounded. The Institute’s Method explains the owner-reported result; its capability manifest declares what the tool can do; and its assessment schema makes the question bank and data contract inspectable. These September 2026 publisher documents describe the assessment. They do not independently establish better customer or business outcomes.
Make meaning explicit before adding an interface
Before the next customer faces the same unresolved choice, identify the improvement that would make the answer more useful. Use the readiness assessment to turn your reported conditions into three starting actions, and keep the next evidence check in view.
Disclaimer
Based on your answers, this assessment suggests improvement priorities; it does not independently verify your business or predict AI recommendations, sales, or business quality.
FAQ
Does the human explanation still matter?
The public page should make the offer understandable to a person. Hidden metadata should not contain stronger or materially different claims. Treat the human description and machine-readable representation as two expressions of the same source truth, with consistent scope, conditions, and responsibility for updates.
How should missing values be preserved?
An unknown fact should remain unknown. Do not fill an empty field with a favorable default merely to make the representation look complete. The consumer needs to know when information is unavailable and whether that gap affects use of the offer or tool.
What does a schema describe?
A schema can define expected fields, allowed values, and related constraints. It helps a client construct or inspect data, but it does not independently prove that the supplied information is true. A valid answer format and a verified business condition are different claims.
What makes a version meaningful?
A version should identify a defined contract or ruleset, not simply make the capability look mature. Record changes that affect inputs, output meaning, or behavior. A consumer needs to know when an integration or interpretation should be reviewed because the underlying contract has changed.
What belongs in a small integration check?
Identify one supported operation and verify its documented behavior with appropriate non-sensitive inputs. Check the meaning of the result as well as the response. This provides bounded evidence of the integration without claiming universal compatibility or performing unrelated actions on behalf of the user.
Do I need to share contact details before seeing the assessment result?
No. The complete result is available before an optional email request. If a contact commitment has held you back, try the free readiness assessment and read the plan first. Emailing it and consenting to future updates are separate choices. The result remains BY YOUR ACCOUNT.
References
Curtiss Witt. The Decision Economy, updated author-supplied manuscript, Chapter 14 for the quoted decision rule; the supplied manuscript also grounds the framework. Supplied September 2026; unpublished manuscript, so no public URL is asserted.
Google Search Central: Introduction to structured data markup. First-party technical guidance. Markup describes page meaning and should reflect visible content. Technical validity does not demonstrate the usefulness of a decision tool.
OpenAPI Specification 3.1.1. Official specification; October 24, 2024. Explains an HTTP API description. Used for concepts, not a claim that 3.1.1 is the latest specification or the site’s exact version.
Model Context Protocol: What is MCP?. Official protocol documentation. Describes connections between AI applications and external systems. Compatibility, authorization, and useful task behavior still require specific checks.
Decision Economy Institute: live capability manifest. Publisher’s capability declaration, accessed September 10, 2026. Describes the available routes and their limits; not an independent test of every operation.
Decision Economy Institute: How this assessment works. Publisher’s own Method; ruleset de-readiness-1.0.0, accessed September 10, 2026. Not an independent outcomes study.
Decision Economy Institute: Assessment schema and question bank. Publisher’s technical contract; accessed September 10, 2026. Data shape and published question bank, not proof of real-world decision quality.
Continue exploring
What business information should I make clear for AI-assisted customers?
Can a website be easy for AI to access but still be unhelpful?
What are the Four Doors to a decision-support capability?
Tags: machine-readable business; Decision Economy; Decision Economy Institute; Curtiss Witt; customer decisions; decision support; business readiness; DERA; Better Choices; Machine access.