MCP Tools and Annotations
Deep dive into MCP tool definitions: annotation flags, safety matrix, input/output schemas, error scenarios, result content types, related resources, and example patterns. Learn how to document tools that AI assistants can use safely and effectively.
Tools are the primary way AI assistants interact with external systems through MCP. Each tool represents a discrete operation: searching data, creating records, running calculations, or triggering workflows. How you document tools - particularly their annotations - directly influences how safely and effectively the AI uses them.
Annotation Flags
Every MCP tool has four annotation flags that describe its safety and behavioural characteristics. These flags are not mere documentation: MCP clients use them to decide whether to proceed automatically or ask the user for confirmation.
Safety Matrix
NeoArc renders annotation combinations as colour-coded semantic badges in the published viewer. This gives developers and AI assistants an instant visual indicator of each tool's risk profile.
Input and Output Schemas
Tools can reference shared JSON Schema definitions for their input parameters and output structures. NeoArc uses the same schema system across REST APIs, GraphQL types, and MCP tools, enabling cross-API traceability.
Error Scenarios
Document the errors each tool can produce. MCP distinguishes between two categories of errors.
Each error scenario includes a name, description, error code, and a template error message. The LLM uses this information to provide helpful error context to the user rather than raw error codes.
Result Content Types
MCP tools can return different types of content. Specify which content types your tool produces so clients know what to expect.
Related Resources
Tools can declare relationships to MCP resources in the same server. This helps the AI understand data flow: which resources a tool reads from, writes to, or produces.
For example, a search_products tool might be related to a product-catalogue resource, indicating that the tool queries the same data the resource exposes. The viewer renders these as clickable cross-references.
Examples
Concrete input/output examples are essential for both human developers and AI assistants. Each example includes a name, description, input arguments as JSON, and the expected output.
Related Guides
Learn how to document MCP resources: concrete URIs, URI templates with parameters, content types, subscriptions, audience control, and metadata. Understand the difference between tools and resources and when to use each.
Document MCP prompt templates: typed arguments with completion support, expected message flows with role and content type, worked examples with argument-to-output mappings, and prompt engineering patterns for consistent AI behaviour.