Skip to main content
The policy package provides the authorization layer for Toolshed — filtering tools by role and resolving whether tools require approval.

​
filterToolsByRole(tools, role)

Returns only the tools whose paths match at least one pattern in the role: 
import { filterToolsByRole } from "@toolshed/policy";

const visibleTools = filterToolsByRole(allTools, {
  id: "developer",
  name: "Developer",
  patterns: ["github.**", "slack.channels.list"],
});

​
matchPattern(toolPath, pattern)

Tests whether a tool path matches a glob pattern: 
import { matchPattern } from "@toolshed/policy";

matchPattern("github.issues.create", "github.issues.*");  // true
matchPattern("github.issues.create", "github.**");         // true
matchPattern("github.issues.create", "linear.**");         // false
matchPattern("github.issues.create", "*");                 // true
Algorithm: recursive segment-by-segment matching.
  • * matches exactly one segment
  • ** matches zero or more segments

​
resolveAnnotations(tool)

Derives whether a tool requires user approval based on its metadata: 
import { resolveAnnotations } from "@toolshed/policy";

const annotations = resolveAnnotations(tool);
// { requiresApproval: true, reason: "HTTP method POST is not safe" }
Resolution priority (first match wins):
SourceLogic
OpenAPImetadata.httpMethod — GET, HEAD, OPTIONS are safe
GraphQLmetadata.operationType — query is safe, mutation requires approval
MCPmetadata.mcpAnnotations.destructiveHint
PluginFalls back to tool.destructive field

​
Return type

interface ToolAnnotations {
  requiresApproval: boolean;
  reason?: string;
}