Tool Catalog

The tool catalog is MITRITY's registry of every tool, API, service, or resource that your AI agents can interact with. By cataloging tools, you enable fine-grained governance: instead of writing policies against raw action strings, you can assign permissions at the tool level, set rate limits, and track usage patterns.

Overview

Every action an agent performs involves a tool — a function call, API request, database query, file operation, or any other discrete capability. MITRITY maintains a catalog of these tools, each with:

A name and description for human readability
A category for organizational grouping
Match rules that map raw agent actions to catalog entries
Operations that define the types of interactions (read, write, delete, etc.)
Metadata for compliance and security context

When the gateway intercepts an agent action, it matches the action against the tool catalog to determine which tool is being used. This enriches audit events with tool context and enables tool-level permissions.

Tool Categories

Every tool belongs to one of eight categories:

Category	Description	Examples
`storage`	File storage, object storage, blob storage	S3, GCS, Azure Blob, local filesystem
`database`	Relational databases, document stores, key-value stores	PostgreSQL, MongoDB, Redis, DynamoDB
`messaging`	Email, chat, notifications, message queues	SendGrid, Slack, Twilio, SQS, Pub/Sub
`llm`	Large language model APIs and inference endpoints	OpenAI, Anthropic, Azure OpenAI, Vertex AI
`code_execution`	Code interpreters, sandboxes, shell access	Python interpreter, Node.js sandbox, shell commands
`code`	Source code management, version control, CI/CD	GitHub, GitLab, Bitbucket, Jenkins
`network`	HTTP requests, webhooks, DNS, proxy services	Outbound HTTP, webhook delivery, DNS lookups
`custom`	Any tool that does not fit the above categories	Internal APIs, proprietary tools, legacy systems

Categories are used for filtering in the dashboard, grouping in compliance reports, and applying category-wide permissions.

Built-In Tools

MITRITY ships with a curated set of built-in tool definitions covering common AI agent tools. Built-in tools are automatically matched when the gateway detects a recognized action pattern.

Storage Tools

Tool Name	Match Pattern	Operations
`aws-s3`	`s3.`, `aws.s3.`	read, write, delete, list
`gcs`	`gcs.`, `storage.googleapis.`	read, write, delete, list
`azure-blob`	`azure.blob.`, `blob.core.windows.`	read, write, delete, list
`local-filesystem`	`fs.`, `file.`	read, write, delete, list

Database Tools

Tool Name	Match Pattern	Operations
`postgresql`	`db.postgres.`, `pg.`	read, write, delete, execute
`mongodb`	`db.mongo.`, `mongo.`	read, write, delete, list
`redis`	`db.redis.`, `redis.`	read, write, delete, list
`dynamodb`	`db.dynamo.`, `dynamodb.`	read, write, delete, list

Messaging Tools

Tool Name	Match Pattern	Operations
`sendgrid`	`email.send`, `sendgrid.`	send
`slack`	`slack.`, `chat.slack.`	send, read, list
`twilio`	`sms.`, `twilio.`	send

LLM Tools

Tool Name	Match Pattern	Operations
`openai`	`llm.openai.`, `openai.`	execute
`anthropic`	`llm.anthropic.`, `anthropic.`	execute
`azure-openai`	`llm.azure.`, `azure.openai.`	execute
`vertex-ai`	`llm.vertex.`, `vertex.`	execute

Code Execution Tools

Tool Name	Match Pattern	Operations
`python-interpreter`	`code.python.`, `exec.python.`	execute
`nodejs-sandbox`	`code.node.`, `exec.node.`	execute
`shell`	`code.shell.`, `exec.shell.`, `bash.*`	execute

Code Management Tools

Tool Name	Match Pattern	Operations
`github`	`github.`, `git.github.`	read, write, delete, list, execute
`gitlab`	`gitlab.`, `git.gitlab.`	read, write, delete, list, execute

Network Tools

Tool Name	Match Pattern	Operations
`http-outbound`	`http.`, `https.`, `network.http.*`	read, write
`webhook`	`webhook.`, `network.webhook.`	send

Match Rules

Match rules determine how raw agent actions map to tool catalog entries. Each tool has one or more match rules.

Action Type Patterns

Action type patterns use glob syntax to match the action_type field of agent actions:

Pattern	Matches	Does Not Match
`s3.*`	`s3.get_object`, `s3.put_object`	`gcs.get_object`
`db..`	`db.postgres.query`, `db.redis.get`	`db.query`
`email`	`email.send`, `send_email`, `email_forward`	`slack.send`

Resource Patterns

Resource patterns match the resource field of agent actions, typically a URL or resource identifier:

Pattern	Matches
`.s3.amazonaws.com/`	`my-bucket.s3.amazonaws.com/data/file.csv`
`https://api.openai.com/*`	`https://api.openai.com/v1/chat/completions`
`postgres://:5432/`	`postgres://prod-db:5432/myapp`

Combined Matching

A tool matches when both the action type pattern and resource pattern match (if both are specified). If only an action type pattern is specified, the resource pattern is ignored.

{
  "name": "production-database",
  "category": "database",
  "match_rules": [
    {
      "action_type_pattern": "db.postgres.*",
      "resource_pattern": "postgres://prod-*:5432/*"
    }
  ]
}

This tool only matches PostgreSQL operations against production databases.

Operations

Operations define the types of interactions a tool supports. They are used for permission assignment (e.g., grant read-only access to a database tool).

Operation	Description	Examples
`read`	Retrieve data without modification	SELECT query, GET request, file read
`write`	Create or update data	INSERT/UPDATE, PUT/POST request, file write
`delete`	Remove data	DELETE query, DELETE request, file delete
`list`	Enumerate resources	List buckets, list tables, directory listing
`execute`	Run code or invoke a function	Code execution, function call, stored procedure
`send`	Send a message or notification	Email send, chat message, SMS

A single agent action can involve multiple operations. For example, a database migration might involve read (inspect schema), write (create table), and execute (run migration script).

Creating Custom Tools

When your agents use tools not covered by the built-in catalog, create custom tool definitions.

Via the Dashboard

Navigate to Tools > Tool Catalog.
Click Add Tool.
Fill in the tool details:
- Name: A unique identifier (e.g., internal-crm-api)
- Display name: Human-readable name (e.g., "Internal CRM API")
- Description: What this tool does
- Category: Select from the 8 categories
- Match rules: Add one or more action type and/or resource patterns
- Operations: Select the operations this tool supports
Click Create Tool.

Via the API

curl -X POST https://api.mitrity.com/api/v1/tools \
  -H "Authorization: Bearer mk_live_your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "internal-crm-api",
    "display_name": "Internal CRM API",
    "description": "Company CRM system REST API for managing contacts, deals, and accounts",
    "category": "custom",
    "match_rules": [
      {
        "action_type_pattern": "crm.*",
        "resource_pattern": "https://crm.internal.company.com/api/*"
      },
      {
        "action_type_pattern": "read_crm_*"
      },
      {
        "action_type_pattern": "write_crm_*"
      }
    ],
    "operations": ["read", "write", "delete", "list"],
    "metadata": {
      "owner": "sales-engineering",
      "data_classification": "confidential",
      "compliance_tags": ["gdpr", "pii"]
    }
  }'

Response:

{
  "data": {
    "id": "tool_crm_8k2m",
    "name": "internal-crm-api",
    "display_name": "Internal CRM API",
    "description": "Company CRM system REST API for managing contacts, deals, and accounts",
    "category": "custom",
    "is_builtin": false,
    "match_rules": [
      {
        "action_type_pattern": "crm.*",
        "resource_pattern": "https://crm.internal.company.com/api/*"
      },
      {
        "action_type_pattern": "read_crm_*"
      },
      {
        "action_type_pattern": "write_crm_*"
      }
    ],
    "operations": ["read", "write", "delete", "list"],
    "metadata": {
      "owner": "sales-engineering",
      "data_classification": "confidential",
      "compliance_tags": ["gdpr", "pii"]
    },
    "created_at": "2026-03-01T10:00:00Z",
    "updated_at": "2026-03-01T10:00:00Z"
  },
  "meta": {
    "request_id": "req_tool001",
    "timestamp": "2026-03-01T10:00:00Z"
  }
}

Tool Metadata

Custom tools support arbitrary metadata fields for organizational and compliance purposes:

Field	Description	Example
`owner`	Team or individual responsible for the tool	`"sales-engineering"`
`data_classification`	Data sensitivity level	`"public"`, `"internal"`, `"confidential"`, `"restricted"`
`compliance_tags`	Compliance frameworks that apply	`["gdpr", "pii", "sox"]`
`documentation_url`	Link to tool documentation	`"https://wiki.company.com/crm-api"`
`deprecation_date`	Scheduled deprecation date	`"2026-12-31"`

Metadata is included in compliance reports and can be used to filter the tool catalog.

API Reference

List All Tools

curl https://api.mitrity.com/api/v1/tools \
  -H "Authorization: Bearer mk_live_your-api-key"

Query parameters:

Parameter	Type	Description
`category`	string	Filter by category (e.g., `database`, `custom`)
`is_builtin`	boolean	Filter by built-in vs custom tools
`search`	string	Search by name or description
`limit`	integer	Results per page (default: 25, max: 100)
`cursor`	string	Pagination cursor

Response:

{
  "data": [
    {
      "id": "tool_s3_builtin",
      "name": "aws-s3",
      "display_name": "AWS S3",
      "category": "storage",
      "is_builtin": true,
      "operations": ["read", "write", "delete", "list"],
      "match_rules": [
        { "action_type_pattern": "s3.*" },
        { "action_type_pattern": "aws.s3.*" }
      ]
    },
    {
      "id": "tool_crm_8k2m",
      "name": "internal-crm-api",
      "display_name": "Internal CRM API",
      "category": "custom",
      "is_builtin": false,
      "operations": ["read", "write", "delete", "list"],
      "match_rules": [
        { "action_type_pattern": "crm.*", "resource_pattern": "https://crm.internal.company.com/api/*" }
      ]
    }
  ],
  "meta": {
    "request_id": "req_tool002",
    "timestamp": "2026-03-01T10:05:00Z",
    "next_cursor": null,
    "total": 2
  }
}

Get a Single Tool

curl https://api.mitrity.com/api/v1/tools/tool_crm_8k2m \
  -H "Authorization: Bearer mk_live_your-api-key"

Update a Tool

curl -X PATCH https://api.mitrity.com/api/v1/tools/tool_crm_8k2m \
  -H "Authorization: Bearer mk_live_your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Updated CRM API description",
    "match_rules": [
      {
        "action_type_pattern": "crm.*",
        "resource_pattern": "https://crm.internal.company.com/api/v2/*"
      }
    ]
  }'

Delete a Custom Tool

curl -X DELETE https://api.mitrity.com/api/v1/tools/tool_crm_8k2m \
  -H "Authorization: Bearer mk_live_your-api-key"

Built-in tools cannot be deleted. Custom tools with active agent permissions will prompt a confirmation warning.

Tool Usage Analytics

The dashboard provides analytics on tool usage across your agents:

Usage by tool: Which tools are most frequently accessed
Usage by agent: Which agents use the most tools
Usage by operation: Read vs write vs delete distribution
Denied operations: Which tool operations are most frequently denied by policies
Trend over time: Tool usage trends over days, weeks, or months

Access tool analytics at Tools > Analytics in the dashboard.

Best Practices

Catalog All Tools Early

Create tool definitions before writing policies. A well-cataloged tool set makes policy writing simpler and more expressive.

Use Specific Match Rules

Prefer specific action type patterns over broad wildcards. crm.contact.read is more governable than crm.*.

Add Compliance Tags

Tag tools with relevant compliance frameworks (gdpr, pii, sox). This makes compliance reporting automatic and accurate.

Review Built-In Matches

Review the built-in tool match rules periodically. If your agents use custom action naming conventions, the built-in patterns may not match. Create custom tools to fill gaps.

Organize by Data Classification

Use the data_classification metadata field consistently across all custom tools. This enables dashboards and reports that show which agents access which sensitivity levels.