Boost (or demote) a specific file in PageRank-driven ranking by setting a multiplicative weight on its PageRank score. Use to surface canonical examples, architectural keystones, or files central to a work-in-progress feature. Capped at 50 active pins per project. Returns JSON: { ok, pin? }.
AI agents use pin_file to create or update resources in Trace — usually the action step of a workflow, after the agent has gathered context. Every call changes real data in your Trace environment.
This tool creates or modifies ranking metadata for files without deleting data, executing code, or causing irreversible changes. It's a configuration/preference adjustment that affects how the code intelligence system prioritizes file visibility. The effect is reversible and scoped to ranking weights, making it a Write operation.
From the tool's definition Tool description states it 'sets a multiplicative weight' on file ranking, which modifies metadata about how files are ranked/prioritized in the system.
Documented attack patterns abuse exactly the kind of access pin_file gives an agent:
PolicyLayer is an MCP gateway — it sits between your AI agents and Trace, and nothing reaches the server without passing your rules. This is the rule we recommend for pin_file:
{
"version": "1",
"default": "deny",
"tools": {
"pin_file": {
"limits": [
{
"counter": "pin_file_rate",
"window": "minute",
"max": 30,
"scope": "grant"
}
]
}
}
}pin_file stays usable, but capped — an agent stuck in a loop can't make hundreds of changes a minute. Everything else on the server is denied unless you say otherwise.
Free to start. No card required.
Boost (or demote) a specific file in PageRank-driven ranking by setting a multiplicative weight on its PageRank score. Use to surface canonical examples, architectural keystones, or files central to a work-in-progress feature. Capped at 50 active pins per project. Returns JSON: { ok, pin? }. It is categorised as a Write tool in the Trace MCP Server, which means it can create or modify data. Consider rate limits to prevent runaway writes.
Register the Trace MCP server in PolicyLayer and add a rule for pin_file: allow, deny, rate-limit, or require approval. Point your MCP client at the PolicyLayer proxy URL and the rule is enforced on every call, before it reaches Trace. Nothing to install.
pin_file is a Write tool with medium risk. Write tools should be rate-limited to prevent accidental bulk modifications.
Yes. Add a rate_limit block to the pin_file rule in your PolicyLayer policy. For example, setting max: 10 and window: 60 limits the tool to 10 calls per minute. Rate limits are tracked per agent session and reset automatically.
Set action: deny in the PolicyLayer policy for pin_file. The AI agent will receive a policy violation error and cannot call the tool. You can also include a reason field to explain why the tool is blocked.
pin_file is provided by the Trace MCP server (nikolai-vysotskyi/trace-mcp). PolicyLayer sits as a proxy in front of this server to enforce policies before tool calls reach the server.
Deterministic rules across all 178 Trace tools. Per-identity grants. Full audit log. Live in minutes. Nothing to install.
Free to start. No card required.
178 Trace tools catalogued and risk-classified — across an index of 42,500+ MCP servers.