A Model Context Protocol connection makes an external capability discoverable. It does not make that capability safe, accurate or authorized. For a Claude architect, those are separate obligations: decide which operations belong in the integration, describe them clearly enough for the model to choose correctly, and place actual authentication, business rules and failure handling in the service that executes them.<\/p>\n
Tool Design & MCP Integration represents 18% of the published Claude Certified Architect \u2013 Foundations<\/a> blueprint. A sound approach to this domain begins with an API design review rather than memorizing MCP vocabulary. The useful question is not whether a tool can be called, but whether a model-directed system can call it safely, interpret the result and recover from a bad one.<\/p>\n Suppose a procurement assistant needs to check a supplier’s approved payment terms before drafting an invoice exception request. A careless tool might expose `run_sql(query)` or a broad `get_supplier(id)` response containing banking details, private contacts and unrelated purchase history. Both make the integration easy to build and difficult to govern. The assistant does not need unrestricted SQL, and the model should not receive information outside the task.<\/p>\n A better capability is something like Tools should be shaped around actions a legitimate user actually needs: locate a policy revision, retrieve a permitted order summary, prepare\u2014but not commit\u2014a change request. This makes tool selection easier to explain and reduces the effect of a mistaken model choice. If changing supplier payment terms would be consequential, split proposing from committing and put the latter behind a separate, enforced authorization path.<\/p>\n Consider two similar tools, one for current policy and one for historical policy revisions. If both are described as \u201cretrieve policy,\u201d Claude has little basis for choosing safely. The descriptions should state the intended decision, required input, source restrictions, and what the output means. Describe when the tool must not<\/em> be used as carefully as when it should be used. A current-terms lookup must not pretend to answer a question about the supplier’s 2023 contract.<\/p>\n Define a small, explicit input schema. An identifier should have a known shape; a requested period should be unambiguous; optional fields should not silently broaden access. Anthropic’s tool-use API lets developers express input requirements with JSON Schema, and strict tool mode can constrain calls to supported schema shapes. That reduces invalid parameters. It cannot replace a service-side check that the user has the right to see the requested record.<\/p>\n Descriptions are part of the model-facing choice surface, not security policy. The server remains responsible for verifying the session, validating business rules, limiting access, rate-limiting operations and recording sufficient audit evidence. A malicious user cannot legitimately become an approver by typing an \u201capproved by CFO\u201d field into a prompt, even if the resulting tool arguments pass schema validation.<\/p>\n MCP commonly exposes different classes of capability. A tool<\/em> represents a callable operation; a resource<\/em> makes information available; a prompt<\/em> can offer a reusable interaction template. Those concepts help organize an integration, but none should be used as a shortcut around access control. A resource URL can still point to sensitive material, and a prompt template can still include untrusted words that must not be promoted to system authority.<\/p>\n Consider exposing a policy corpus. Read-only policy documents may be appropriate as resources that an authorized client can retrieve, while a narrowly scoped function handles the action of looking up a current effective policy. A separate approval operation belongs in an application that checks delegated authority. Putting all three into an undifferentiated \u201ccompany knowledge\u201d tool makes the system harder to test and easier to over-permission.<\/p>\n An MCP server’s published capability list also needs lifecycle management. The installed server version, enabled tools, permissions and underlying provider API may change while the client’s prompt remains the same. Review permissions after deployment changes and test that a tool no longer needed by the workflow is not merely hidden from the prompt but remains inaccessible to the executing identity.<\/p>\n Suppose the supplier lookup returns an empty list. Is the supplier genuinely absent, is the caller unauthorized, or is the database unavailable? If the result says only \u201cno matches,\u201d Claude may reach the wrong business conclusion. A model can be excellent at reasoning over text and still be misled by an ambiguous service contract.<\/p>\n A useful tool result contains a distinct state and structured details. Anthropic’s tool-result conventions support signaling execution errors with Start with the business capability, not a database table<\/h2>\n
read_authorized_supplier_terms<\/code>. Its inputs identify the supplier and the current business context, while the server derives the requesting identity from the authenticated session rather than trusting a model-supplied user ID. The response returns the approved terms, a verification timestamp, a stable source reference and, when relevant, a reason the information cannot be released. The application can then decide whether a draft exception is justified without exposing a financial account number.<\/p>\nGive tool descriptions enough discrimination to be useful<\/h2>\n
Understand the MCP boundary without confusing its elements<\/h2>\n
Design errors that a model cannot mistake for success<\/h2>\n
is_error<\/code>; a tool-specific business payload can additionally indicate business states such as not found, forbidden or inconsistent data. Do not rely on an English sentence hidden in a long blob to communicate whether the operation failed.<\/p>\n