mcfortigate

Overview Schema Source Related Servers Discussions Admin

Find what references an object

find_references

Read-onlyIdempotent

Find what references a firewall address, service, virtual IP, or interface before you change it. Returns a verdict, direct and transitive references, and safe_to_delete from the appliance.

Instructions

Find what references an address, service, or interface, before changing it.

This answers the question that precedes every firewall change, which is whether something is safe to touch.

The authority is the appliance itself. FortiOS exposes the same reference lookup its web UI uses, which knows every table that can hold a reference, seventy-four of them for a firewall address on 7.0.14. This tool asks that endpoint and reports what it says in references. It also scans policies, groups, virtual IPs, and static routes directly, because those yield readable detail the endpoint does not, such as a policy's name and action.

Read verdict rather than inferring from a count:

referenced, something points at it
no_references, the appliance confirmed nothing does
no_references_in_checked_scopes, the authoritative lookup was unavailable and a partial scan found nothing, which is a fact about four tables rather than about the appliance
object_not_found, no address, group, service, virtual IP, or interface by this name exists, so the question is probably a typo
indeterminate, something needed could not be read

safe_to_delete appears only for the first two, because a table this tool could not read cannot support a claim that nothing references the object. A denied read is the likely outcome for a correctly least-privileged token, so an incomplete answer is normal rather than exceptional, and sources_checked names what failed.

The two lists count different things, and will disagree without being in conflict. total_references and references count reference sites: a policy using one address as both its source and its destination is two. The detail lists (policies, groups, vips, routes) count objects, so the same policy appears once there, with referenced_as naming both roles. Neither number is wrong; prefer references when reporting what must be changed before a delete, and the detail lists when naming the objects an operator has to open.

Containers are walked through, and the results are kept separate. references holds what the appliance named directly and every row carries depth: 0. transitive_references holds what was reached through an address group, a service group, a zone, or a switch: each row carries the depth it was found at and a via chain of the container names that led to it. The distinction is the remedy. A direct reference is removed from the object holding it; a transitive one is removed by editing a container or a member list, and the policy that stops matching is not the object you edit.

expansion reports how far the walk got. status is complete when the chain ran out, depth_capped when it hit the ceiling with containers still unopened, which are then named in unexpanded, and incomplete when something along the way could not be read. Only complete means the transitive list is the whole blast radius.

Input Schema

TableJSON Schema

Name	Required	Description
`vdom`	No	Virtual domain to search. Defaults to the one configured for this target. An object with the same name can exist in several vdoms, and this answer is about one of them.
`target`	No	Which FortiGate to query. Optional when only one is configured.
`object_name`	Yes	Exact name of the address, group, service, virtual IP, or interface. Matching is exact, not a search.

Output Schema

TableJSON Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.1.0Sep 12, 2026

TDQS

A4.4/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With annotations already declaring read-only, idempotent, and open-world behavior, the description adds rich operational context: the authoritative endpoint, supplementary direct scans, verdict semantics, when safe_to_delete is available, expected denied reads, the distinction between reference sites and objects, transitive reference handling, and expansion completeness. This is substantially more than the annotations provide.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is long but well-structured with front-loaded purpose and bulleted verdict explanations. Every section appears to serve a distinct need for interpreting this tool's complex output, though some of the prose could be tightened without losing information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the complexity of the reference lookup, the need to interpret verdicts and counts, and the existence of an output schema, the description is complete enough for an agent to call and interpret the tool correctly. It covers when to use it, how results are assembled, and how to read the return fields, leaving no critical gap.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so all three parameters (object_name, vdom, target) are already documented in the schema. The description adds no further parameter-level detail such as matching syntax, vdom semantics, or target selection beyond what the schema states, so the baseline of 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb ('Find') and resource ('what references an address, service, or interface') and frames the tool's purpose as answering a pre-change safety question. It is clearly distinct from sibling list_* tools and search_config, which enumerate or search configurations rather than resolving references.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It explicitly says when to use ('before changing it') and what question it answers ('whether something is safe to touch'). However, it does not name alternative tools (e.g., search_config) or state when not to use this tool, leaving some routing inference to the agent.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server