Most API documentation is written for humans.
MCP tool descriptions are different.
They are read by the model that decides what to call next.
That means tool names, descriptions, schemas, and error messages are not just documentation garnish. They are part of the safety boundary.
A bad tool asks the model to guess
A risky MCP tool often looks like this:
- name:
query - input: free-form string
- description: “Run SQL against the database”
Technically simple.
Operationally vague.
The model has to infer when to use it, what is safe, which tables matter, and what failure means.
That is not a production boundary. That is a shrug with JSON around it.
A better tool is boring on purpose
For database workflows, the tool should make the safe path obvious:
query_customer_usage_readonly- approved schemas or views
- structured filters instead of arbitrary commands
- explicit “do not use for exports or personal data lookup” guidance
- clear result limits
- audit logging
- useful access-denied errors
The database permissions still need to enforce the boundary.
But the model-facing contract matters too.
If the description does not say when not to use the tool, the model will often try anyway.
Errors matter too
“Permission denied” is technically correct.
It is not very helpful for an agent.
A better error explains the safe next step:
This request tried to access a table outside the approved reporting scope. Ask an administrator to add the table to the approved view set, or reformulate the question using customer_usage_summary.
That keeps the agent inside the workflow instead of nudging it toward improvisation.
Conexor focuses on this MCP infrastructure layer: controlled tools for databases and APIs across Claude, ChatGPT, Cursor, n8n, Continue, and other MCP clients.
Longer post: MCP tool descriptions are a security boundary, not documentation garnish
Treat MCP descriptions like the model-facing part of your access policy.
Not comments in code.
Top comments (0)