Provides tools for interacting with FortiAnalyzer, Fortinet's log management and analytics platform, including system health, ADOM and device inventory, alerts, reports, LogView searches, and documented read endpoints via the JSON-RPC API.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@FortiAnalyzer MCP Server What's the current system status and device inventory?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
A Python Model Context Protocol server for the FortiAnalyzer JSON-RPC API. It provides structured tools for system health, ADOM and device inventory, alerts, reports, LogView searches, and documented long-tail read endpoints.
The bundled offline catalog contains searchable factual metadata derived from the public FortiAnalyzer JSON-RPC API documentation. It includes generated summaries and links back to each source page; the source documentation itself is not redistributed in this repository. See NOTICE for provenance and licensing details.
The searchable catalog preserves the guide's published endpoint paths. Endpoint compatibility can vary by appliance release, so validate the tools you plan to use in a non-production environment first.
This is an independent project and is not affiliated with or endorsed by Fortinet. Fortinet and FortiAnalyzer are trademarks of Fortinet, Inc.
API-key and username/password session authentication
Secure TLS verification by default, with custom CA support
Lazy, concurrency-safe login and one read retry after documented session
expiry (-10)
Bounded LogView submit/poll/fetch/cleanup workflows
Structured MCP output with request and endpoint metadata
Offline API-document metadata search plus an opt-in generic read tool
Server-managed credentials and session IDs are never exposed in tool schemas or server-generated metadata
Generic state-changing access disabled by default
stdio, Streamable HTTP, and SSE transports
Related MCP server: Zabbix MCP Server
Python 3.10 or newer
Network access to a FortiAnalyzer appliance
A least-privileged FortiAnalyzer API user
A FortiAnalyzer release that supports the selected JSON-RPC endpoints
git clone https://github.com/forticrevs/fortianalyzer-mcp.git
cd fortianalyzer-mcp
python3 -m venv .venv
. .venv/bin/activate
python -m pip install .Copy the example environment file and configure one authentication method:
cp .env.example .envAPI-key authentication is preferred for long-running automation:
FAZ_HOST=https://fortianalyzer.example.com
FAZ_API_KEY=replace-with-a-secret-from-your-secret-store
FAZ_VERIFY_SSL=trueSession authentication is also supported:
FAZ_HOST=https://fortianalyzer.example.com
FAZ_USERNAME=mcp-readonly
FAZ_PASSWORD=replace-with-a-secret-from-your-secret-store
FAZ_VERIFY_SSL=trueDo not commit .env; it is ignored by Git.
Run the stdio server:
fortianalyzer-mcpAn MCP client can launch that executable directly. A representative client configuration is:
{
"mcpServers": {
"fortianalyzer": {
"command": "/absolute/path/to/.venv/bin/fortianalyzer-mcp",
"env": {
"FAZ_HOST": "https://fortianalyzer.example.com",
"FAZ_API_KEY": "${FAZ_API_KEY}",
"FAZ_VERIFY_SSL": "true"
}
}
}
}Environment interpolation depends on the MCP client. If it is unsupported, use the client's secret facility or arrange for the server process to inherit the variables.
Tool | Purpose |
| Search bundled API-guide metadata and public source URLs |
| Show non-secret local connection settings |
| Read version, model, license, disk, and memory status |
| Read CPU, memory, and disk performance |
| Inspect administrative domains |
| List managed devices in an ADOM |
| List unregistered devices |
| Query bounded event-management alerts |
| Read basic and correlation event-handler configuration |
| List SQL report layouts |
| List report templates |
| List report schedules |
| Read global log-forwarding configuration |
| Run a bounded one-page LogView workflow |
| Start a manual/paginated LogView task |
| Poll or page through a LogView task |
| Cancel and release a LogView task |
| Call an appliance-local endpoint with JSON-RPC |
faz_raw_write is registered only when FAZ_ENABLE_WRITE_TOOLS=true. It
requires confirm=true, cannot call authentication or reboot endpoints, and
does not automatically replay a mutation after session expiry or an ambiguous
transport failure. The confirmation argument and MCP annotations are not an
authorization or human-approval boundary. Enabling this tool grants connected
clients broad mutation capability within the FortiAnalyzer account's
permissions; use a separate least-privileged account and an external approval
control. Keep it disabled for read-only deployments.
Device scope is always explicit. Use a concrete list such as
["branch-fgt-01"]; use ["All_FortiGate"] only intentionally.
Relative searches default to the last hour. Absolute times must be paired, FortiAnalyzer-local timestamps:
2025-01-15 09:00:00By default:
a specific-device search is limited to 24 hours;
an all-device search is limited to 1 hour;
one tool result is limited to 200 rows;
LogView fetch pages never exceed the appliance limit of 500 rows;
at most eight LogView searches can be active or starting concurrently;
the convenience workflow times out after 30 seconds;
task deletion is attempted after completion, timeout, errors, and server shutdown; failed cleanup remains tracked for a later shutdown retry.
For pagination, start a task and retrieve each required offset. A completed full
page does not prove that all rows were consumed, so the server conservatively
keeps that task alive even when cleanup_when_done=true. Set
cleanup_when_done=false while managing pages explicitly, then call
faz_cancel_log_search. The convenience faz_search_logs workflow intentionally
returns one page and always attempts to release its task.
Variable | Default | Meaning |
| required | HTTPS origin, optionally ending in |
|
|
|
| Bearer API key ( | |
| Session credentials | |
|
| Verify the appliance certificate |
| PEM bundle for a private CA | |
|
| Explicit development-only HTTP opt-in |
|
| Normal API timeout |
|
| Default ADOM |
|
| Maximum rows accepted by bounded tools |
|
| Convenience search timeout |
|
| Specific-device search window |
|
| All-device search window |
|
| Maximum active/starting LogView tasks |
|
| Register the guarded raw mutation tool |
|
|
|
|
| Network transport bind address |
|
| Network transport port |
| Comma-separated browser-origin allowlist | |
| Additional comma-separated Host header allowlist | |
|
| Streamable HTTP stateless mode |
|
| Use JSON rather than SSE response bodies |
|
| Server logging level |
For self-signed appliance certificates, install the issuing CA and set
FAZ_CA_BUNDLE. FAZ_VERIFY_SSL=false is available for development but should
not be used in production.
Network transports do not add client authentication to the MCP endpoint. Keep the default loopback binding or place the server behind an authenticated, TLS-protected gateway.
Browser clients must be explicitly allowed. For example:
FAZ_MCP_ALLOWED_ORIGINS=http://model.example.test,https://another-ui.exampleOrigins are exact HTTP(S) origins without paths or trailing slashes. A terminal
port wildcard such as http://model.example.test:* is supported. The setting drives
both DNS-rebinding validation and CORS/preflight responses. Localhost origins
remain allowed automatically. If a proxy forwards a non-local Host header,
allow that separately, for example
FAZ_MCP_ALLOWED_HOSTS=model.example.test,model.example.test:*.
These allowlists are request-validation controls, not client authentication.
Install the development extra and run the test suite:
python -m pip install -e '.[dev]'
pytestRebuild the offline catalog from a documentation tree you are authorized to use:
python scripts/build_catalog.py \
--source /path/to/fortianalyzer-api-docs \
--output src/fortianalyzer_mcp/data/api_catalog.jsonThe automated suite uses mocked HTTP transports and does not require an appliance. Validate against your appliance because releases can differ in endpoint-specific request and response fields.
faz_raw_get accepts any syntactically valid appliance-local path except
blocked authentication paths; catalog membership is guidance, not an enforced
allowlist. It prevents request-field overrides and always sends JSON-RPC
get, but returns endpoint data without field-level redaction or a generic
response-size cap. Use a least-privileged account, call only trusted endpoints,
and pass endpoint-specific limit, range, or field-selection parameters.
Cancel and delete a LogView task to release FortiAnalyzer resources.
| Name | Required | Description | Default |
|---|---|---|---|
| tid | Yes | ||
| adom | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description says 'delete a LogView task,' which is a destructive action, but annotations declare destructiveHint=false. This is a direct contradiction. The description also fails to disclose any other behavioral details, such as permissions or side effects, beyond what annotations already state.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence with no unnecessary words. However, it is under-specified for the tool's complexity, so while it is structurally efficient, the brevity comes at the expense of critical information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Even with an output schema present, the description is too sparse. It doesn't explain the required tid parameter, the optional adom, or the cancellation behavior. It also contradicts annotations, making it incomplete for safe and correct use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0% description coverage, with only names 'tid' and 'adom' and a required flag. The description provides no parameter semantics, so it doesn't help the agent understand what tid refers to (the task ID) or the role of adom. With low schema coverage, the description must compensate, but it does not.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Cancel and delete') and the resource ('a LogView task'), along with the purpose ('to release FortiAnalyzer resources'). It distinguishes this tool from siblings like faz_start_log_search and faz_get_log_search by the specific action of canceling/deleting a task.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is used when a LogView task is no longer needed and resources should be freed, but it provides no explicit when-to-use guidance, exclusions, or alternatives. Without context about when to choose this over related tools, agents must infer usage from the name and siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Show non-secret connection and safety configuration.
This does not make an appliance request and never returns credentials or session identifiers.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnly, idempotent, and non-destructive hints, but the description adds significant context: no appliance request and no credentials/session identifiers. This goes beyond the annotations to clarify network behavior and sensitive data handling.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the core purpose, and every sentence adds value. It is concise without being under-specified.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a parameterless tool with an output schema, the description covers the essential context: what it shows (connection/safety config), what it doesn't do (no appliance request), and what it excludes (credentials/session IDs). This is complete for the tool's simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so per the rubric the baseline is 4. The description doesn't need to explain parameters; it adds context about the nature of the result (non-secret configuration) without redundancy.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Show') and resource ('connection and safety configuration'), making the tool's purpose immediately clear. It is clearly distinct from sibling tools which focus on lists, searches, and system metrics.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context by stating it does not make an appliance request and never returns credentials, implying it's a safe local info tool. However, it does not explicitly mention alternatives or exclusions relative to sibling tools, so it loses a point.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get one ADOM. An empty ADOM uses FAZ_DEFAULT_ADOM.
| Name | Required | Description | Default |
|---|---|---|---|
| adom | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare read-only/idempotent behavior, so the description doesn't need to repeat that. It adds a useful behavioral detail: an empty adom parameter falls back to FAZ_DEFAULT_ADOM. This goes beyond the schema, which provides no description for the parameter.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is remarkably concise—two sentences that cover purpose and a key parameter behavior. It is properly front-loaded with the primary action in the first sentence and no extraneous content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter getter with rich annotations and an output schema, the description covers the essential purpose and a critical edge case (empty ADOM). It does not address invalid ADOM names, but that is not necessary given the annotations and output schema; the description is adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description fully compensates by explaining the parameter's behavior: an empty ADOM uses FAZ_DEFAULT_ADOM. It directly clarifies what the 'adom' string means and how the default value works, which is essential for correct invocation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific action ('Get one ADOM') using a specific verb and resource, distinguishing it from sibling tools like faz_list_adoms by indicating it retrieves a single item. The additional sentence about empty ADOM adds relevant context without muddling the purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description establishes clear context: this tool fetches a single ADOM, and notes behavior when no ADOM is specified. It does not explicitly mention alternatives or exclude other tools, but the 'one' versus 'list' differentiation is implied by the verb and the sibling tool names.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Poll or fetch one page from a LogView task.
The task is deleted automatically only after FortiAnalyzer proves that this is the last page. A full page is retained conservatively because more rows may exist; fetch the next offset or call faz_cancel_log_search. Set cleanup_when_done=false whenever pagination is managed explicitly.
| Name | Required | Description | Default |
|---|---|---|---|
| tid | Yes | ||
| adom | No | ||
| limit | No | ||
| offset | No | ||
| cleanup_when_done | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses key lifecycle behavior: the task is deleted only after FortiAnalyzer proves the last page, and a full page is retained conservatively to avoid missing rows. This goes beyond the annotations (which only say readOnlyHint=false, idempotentHint=false) and explains the resource cleanup semantics, a critical behavioral trait for a poll-style tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is four sentences, each adding value: purpose, lifecycle, retention rationale, and explicit parameter guidance. It is front-loaded with the action and avoids redundancy, making it efficient and easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (pagination lifecycle, cleanup, return data), the description covers the most error-prone aspects: when the task is deleted, how to proceed, and when to disable auto-cleanup. However, it omits details about the return structure (mitigated by output schema) and the meaning of adom/limit, leaving some contexts incomplete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It explains cleanup_when_done and offset meaningfully, but does not clarify tid (required), adom, or limit. This is a clear gap, leaving some parameters ambiguous, though the name and context imply their roles.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action: 'Poll or fetch one page from a LogView task.' This clearly identifies the tool's purpose and resource, and the mention of 'fetch the next offset or call faz_cancel_log_search' differentiates it from sibling tools like faz_start_log_search and faz_cancel_log_search.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit guidance on when to set cleanup_when_done=false ('whenever pagination is managed explicitly') and describes the automatic deletion behavior for the last page. It implies the tool is for iterative fetching, but does not explicitly state prerequisites like needing a task ID from faz_start_log_search or contrast with faz_search_logs.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get current FortiAnalyzer CPU, memory, and disk performance metrics.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, openWorld, idempotent, and non-destructive behavior. The description adds the 'current' aspect (snapshot rather than historical), which is useful context but does not disclose additional traits like rate limits or prerequisites.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no superfluous words. Every part contributes to explaining the tool's function.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simplicity of the tool (zero parameters) and the presence of an output schema, the description sufficiently covers the necessary context. Return values are presumably documented in the output schema, so no further detail is required.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has no parameters, and the schema is empty. With 0 params, the baseline is 4, and the description appropriately adds no parameter-specific details since there is nothing to clarify.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly specifies the verb 'Get' and the resource 'FortiAnalyzer CPU, memory, and disk performance metrics', distinguishing it from sibling tools like faz_get_system_status. The scope (current metrics) is explicit.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context that this tool retrieves current performance metrics, making its intended use obvious. It does not explicitly list exclusions or alternatives, but no such guidance is necessary for such a straightforward read-only getter.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get FortiAnalyzer version, model, hostname, license, disk, and memory status.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, establishing a safe read operation. The description adds no extra behavioral context beyond listing the data returned; it does not mention potential delays, authentication requirements, or other side effects, but the annotations cover the primary safety profile.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no wasted words. It immediately says 'Get FortiAnalyzer' and then lists the attributes, making it highly scannable and concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no parameters, an output schema present, and annotations fully describing safety, the description fully covers the tool's purpose. There is no missing information; even return values are handled by the output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has no parameters, so schema coverage is effectively 100%. According to the rubric, 0 params yields a baseline score of 4. The description adds no parameter semantics, but none are needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific verb ('Get') and resource ('FortiAnalyzer system status') and enumerates the exact attributes (version, model, hostname, license, disk, memory). This fully distinguishes it from siblings like faz_get_system_performance or faz_connection_info.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies a clear use case (retrieving system status) via the name and content. It does not explicitly mention alternatives or exclusions, but the context is unambiguous and no caveats are needed for a parameterless read-only tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List administrative domains, optionally returning only selected fields.
| Name | Required | Description | Default |
|---|---|---|---|
| fields | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, openWorld, idempotent, and non-destructive hints, so the safety profile is covered. The description adds the 'optionally returning only selected fields' behavior, but that is largely redundant with the schema. No additional behavioral traits (e.g., pagination, filtering scope) are disclosed, so it meets the minimum bar but does not exceed it.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that is concise and front-loaded. Every word contributes meaning, and there is no fluff or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With an output schema present, return values need not be described. The tool has only one optional parameter and is a simple list operation. The description is sufficient for this simplicity, though it omits any mention of pagination or result limits, but these are not critical given the output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate for documenting the 'fields' parameter. It does clarify that the parameter controls which fields are returned, but it does not list valid field names or explain the format. This is marginal compensation for the single optional parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'List' and the resource 'administrative domains', which distinguishes it from singular tools like faz_get_adom and other list tools (devices, alerts, etc.). The optional fields clause adds specificity without confusion.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is given about when to use this tool versus alternatives. It does not mention that faz_get_adom retrieves a single ADOM, nor does it provide exclusions or prerequisites. The context is implied only by the name and description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List event-management alerts with bounded pagination.
Times are FortiAnalyzer-local values in YYYY-MM-DD HH:MM:SS form and
must be supplied as a pair. filter_expression uses alert-filter syntax;
prefer event_type and severity for common filters.
| Name | Required | Description | Default |
|---|---|---|---|
| adom | No | ||
| limit | No | ||
| offset | No | ||
| end_time | No | ||
| severity | No | ||
| event_type | No | ||
| start_time | No | ||
| filter_expression | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover read-only, idempotent, non-destructive traits. The description adds important behavioral constraints: times must be supplied as a pair, filter_expression uses a specialized alert-filter syntax, and pagination is bounded. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences cover purpose and key usage guidance with no redundancy. Each sentence earns its place, and the most important information (what it lists) is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a list tool with annotations and an output schema, the description covers the critical usage aspects: purpose, time constraints, and filter preferences. It does not clarify adom or pagination details, but these are less central given the output schema and self-explanatory parameter names. Overall adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It adds meaning for start_time/end_time (pair requirement, format), filter_expression (alert-filter syntax), and recommends event_type/severity for common filters. However, it does not explain other parameters like adom or the pagination semantics, leaving partial gaps.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'List event-management alerts', identifying the specific verb and resource. This distinguishes it from sibling list tools like faz_list_devices and faz_list_report_layouts. 'Bounded pagination' adds useful scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides clear context for using time parameters (must be paired, specific format) and suggests preferring event_type and severity over filter_expression for common filters. Does not explicitly mention alternatives or when-not-to-use, but the resource-specific naming makes usage context fairly clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List managed devices in an ADOM, optionally selecting response fields.
| Name | Required | Description | Default |
|---|---|---|---|
| adom | No | ||
| fields | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, covering the safety profile. The description adds scoping to an ADOM and the optional field selection, which is useful, but does not disclose return format or pagination behavior. This is consistent with a moderate-level addition beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, focused sentence of 11 words, front-loaded with the primary action and resource. Every word contributes meaning, with no redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple two-parameter read-only tool with output schema present, this description covers the essential behavior, scope, and optionality. It does not need to describe return values since an output schema exists, and no critical information is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description compensates partially: 'in an ADOM' gives meaning to the adom parameter, and 'optionally selecting response fields' explains the fields parameter. However, the explanations are basic and lack additional detail like examples or allowed field names, so the semantics are only moderately enriched.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (List), the resource (managed devices), and the scope (in an ADOM), which distinguishes it from sibling tools like faz_list_unregistered_devices and faz_list_adoms. The verb and resource are specific and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The context is clear: use this tool to list managed devices within an ADOM, as opposed to unregistered devices or other resource lists. However, it does not explicitly name alternatives or state when not to use the tool, so it falls short of the explicit guidance in the top-tier example.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List basic and correlation event handlers in an ADOM.
| Name | Required | Description | Default |
|---|---|---|---|
| adom | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, which establish the safety profile. The description adds no additional behavioral context such as pagination, permission requirements, or response structure. It simply restates the listing action, so it adds no extra transparency beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, compact sentence that front-loads the verb and resource. Every word contributes, and there is no redundant or filler content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only listing tool with an output schema available, the description covers the fundamental purpose and scope. It does not mention edge cases like empty ADOM, but given the tool's simplicity and rich annotations, the description is largely sufficient. Some extra notes on ADOM behavior would enhance completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has one optional parameter 'adom' with 0% description coverage. The description only says 'in an ADOM', which vaguely connects the parameter to the tool's scope but does not explain format, required vs optional, or default behavior. This minimal compensation falls short of fully documenting the parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'List' and identifies the resource as 'basic and correlation event handlers' scoped to 'an ADOM'. This clearly distinguishes it from sibling list tools such as faz_list_devices and faz_list_report_templates, which target other resources.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is for retrieving event handlers when needed, and the unique resource name among siblings makes the use case obvious. However, it does not explicitly state when to use this over alternatives or mention any exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List global FortiAnalyzer log-forwarding configurations.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true, so the safety profile is covered. The description adds the 'global' scope, which is useful context, but it does not describe any additional behavioral traits or return format expectations. With annotations present, this is an acceptable baseline.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no redundancy, directly stating the action and target. It is appropriately sized for a zero-parameter list operation and earns its place without wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple, zero-parameter, read-only listing tool with an output schema and comprehensive annotations, the description is complete. It provides enough information for an agent to select and invoke the tool correctly without further detail.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, and the input schema is empty (100% coverage by default). The baseline for 0 parameters is 4 since there is no parameter information to convey. The description does not need to add parameter semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'List' and identifies the resource as 'global FortiAnalyzer log-forwarding configurations', which is clear and distinguishes it from sibling list tools like faz_list_devices or faz_list_alerts. The scope 'global' adds precision beyond just the tool name.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage by clearly naming what is listed, and the zero-parameter scope makes usage straightforward. However, it does not explicitly mention alternatives or when-not-to-use, though this is a simple, self-contained operation. Context is clear with no exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List SQL report layouts in an ADOM.
| Name | Required | Description | Default |
|---|---|---|---|
| adom | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already disclose readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds only that the listing is scoped to an ADOM, which is also visible in the schema. It does not disclose any additional behavioral traits such as pagination or default behavior when adom is empty.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no unnecessary words. It immediately communicates the action and resource, making it highly concise and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple with one optional parameter and has an output schema, but the description lacks parameter semantics and usage guidance. It is minimally viable for a list operation, yet leaves clear gaps about ADOM behavior and alternative selection.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description must compensate for the parameter meaning. It only repeats 'in an ADOM', which adds little beyond the parameter name 'adom'. It does not explain what values are valid, whether the parameter is required, or how it affects the result set.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'List', the resource 'SQL report layouts', and the scope 'in an ADOM'. This distinguishes it from sibling tools like list_report_templates and list_report_schedules by naming a distinct resource type, though it does not explicitly contrast with them.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives, or what happens if the adom parameter is omitted. There are no exclusions, prerequisites, or examples, leaving the agent to infer usage from the name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List configured SQL report schedules in an ADOM.
| Name | Required | Description | Default |
|---|---|---|---|
| adom | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint=true, idempotentHint=true, and destructiveHint=false, which cover the safety profile. The description adds minimal behavioral context by specifying 'configured' schedules and the ADOM scope, but it does not disclose pagination, filtering, or authentication requirements. The description does not contradict the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that starts with the verb 'List', immediately states the resource and scope, and contains no filler or redundant wording. It is appropriately concise for a simple list tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list operation with an output schema and strong annotations, the description covers the core purpose adequately. However, it omits usage context and leaves the 'adom' parameter unexplained, which would require an agent to infer meaning or seek additional documentation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has one parameter 'adom' with no description (0% schema coverage). The description mentions 'in an ADOM' which aligns with the parameter but does not explain its format, optionality, or how to specify the ADOM name. This adds very little beyond the schema's bare title 'Adom'.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'List' and identifies a distinct resource: 'configured SQL report schedules' within an ADOM. This clearly differentiates it from sibling tools like faz_list_report_templates and faz_list_report_layouts, which target different resources.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage through the tool's name and resource scope ('SQL report schedules', 'in an ADOM'), but it does not explicitly state when to use this tool versus alternatives or provide any prerequisites or exclusions. There is no direct guidance, but the context is somewhat inferable.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List available report templates in an ADOM.
| Name | Required | Description | Default |
|---|---|---|---|
| adom | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the description need not repeat safety traits. The description adds the 'in an ADOM' scope, which is useful context, but does not disclose any additional behavioral details such as authentication needs, defaults, or side effects. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that directly states the purpose. Every word earns its place; no filler or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple with one optional parameter and an output schema, so return values need no explanation. However, the description omits parameter behavior (optionality/default), and given the many sibling list tools, it could clarify how report templates differ from layouts/schedules. This leaves minor but noticeable gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%; the 'adom' parameter has no description. The tool description mentions 'in an ADOM', which hints that the adom parameter specifies the ADOM, but it does not explain that the parameter is optional, possible values, or behavior when omitted. This insufficiently compensates for the lack of schema documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('List') and the resource ('available report templates') with a scope ('in an ADOM'). This is specific and distinguishes it from sibling tools like faz_list_report_layouts and faz_list_report_schedules by naming the exact resource type.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when you need report templates, but does not provide explicit when-to-use or when-not-to-use guidance, nor does it mention alternatives among the many sibling list tools. Context is clear but exclusions and alternatives are absent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List devices that are visible to FortiAnalyzer but not registered.
| Name | Required | Description | Default |
|---|---|---|---|
| fields | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds no extra behavioral traits such as pagination, filtering semantics, or interpretation of 'visible.' It does not conflict with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no filler words. It efficiently states the tool's purpose without unnecessary detail. It is appropriately sized for a simple list operation.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Although the tool is simple and has annotations plus an output schema, the description leaves gaps about what 'visible' means and what 'registered' refers to in the FortiAnalyzer context. It is adequate for a minimal tool but doesn't provide a fuller operational picture.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The single optional 'fields' parameter has 0% schema coverage and is not mentioned in the description. Since the description must compensate for the schema's lack of documentation and fails to do so, the parameter semantics are completely unaddressed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the action ('List') and the specific resource ('devices visible to FortiAnalyzer but not registered'). This distinguishes it from sibling tool faz_list_devices, which likely lists registered devices. The one-sentence summary is direct and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use the tool (when you need unregistered devices) but provides no explicit when/when-not guidance or alternative tool names. It doesn't mention that faz_list_devices is for registered devices, but the wording implicitly separates the use case.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Call an appliance-local read endpoint not covered by a high-level tool.
First use faz_search_api_docs to find the candidate path, then consult
its linked source page for parameter placement. Catalog membership is
not enforced. params contains members beside url; credentials,
session, request id, method, and host cannot be overridden. Results are
returned without field-level redaction, and response size is controlled
by the selected endpoint. Use only trusted endpoints and pass documented
limit/range/field selectors when available.
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | ||
| params | No | ||
| jsonrpc_version | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds several behavioral constraints beyond annotations: credentials/session/request ID/method/host cannot be overridden, results have no field-level redaction, response size varies by endpoint, and catalog membership is not enforced. This complements the readOnlyHint, idempotentHint, and openWorldHint annotations without contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a compact paragraph of five sentences, each delivering actionable information without redundancy. It front-loads the core purpose and then provides necessary cautions and usage steps.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a low-level raw GET tool with flexible params and an output schema, the description covers the prerequisite workflow, security constraints, override limitations, and result characteristics. It is sufficiently complete for an agent to select and invoke the tool appropriately.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With schema description coverage at 0%, the description compensates by explaining that params can contain members such as url (while some fields cannot be overridden), and advising to consult the linked source page for parameter placement. It gives meaningful context, though the exact meaning of 'path' and 'jsonrpc_version' is left implicit.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states this tool calls an appliance-local read endpoint not covered by a high-level tool, using a specific verb ('Call') and resource ('appliance-local read endpoint'). It distinguishes itself from siblings by positioning as a low-level fallback and instructing to search docs first.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly directs to use faz_search_api_docs first to find the path and source page for parameter placement, and advises to use only trusted endpoints with documented selectors. This provides clear when-to-use guidance and implicitly says not to use it when a high-level tool exists.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search metadata extracted from the FortiAnalyzer API guide.
Use this before faz_raw_get or when a high-level tool does not cover an endpoint. Results include JSON-RPC methods, API paths, generated summaries, relative source paths, and public documentation URLs. Consult the linked source page for exact request parameters. The catalog is local and does not contact the appliance.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| query | Yes | ||
| category | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
While the annotations already declare the tool read-only and non-destructive, the description adds valuable non-obvious context: 'The catalog is local and does not contact the appliance.' This tells the user that no network call is made, which is beyond what the annotations provide. It also lists result contents, giving a clear picture of what to expect.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences, each earning its place. The first sentence states the purpose, the second provides usage context and result contents, and the third adds a critical behavioral note plus a pointer for further details. It is front-loaded with the core purpose and avoids any redundant or filler wording.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers purpose, usage guidance, behavioral traits, and result content, which is sufficient for a search tool with an output schema. It mentions that results include JSON-RPC methods, API paths, summaries, source paths, and URLs, and advises consulting the source page for exact request parameters. The only notable gap is parameter semantics, but overall context is well covered.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0% description coverage for parameters, and the description does not explain any of the three parameters (query, limit, category). While 'query' and 'limit' are somewhat self-explanatory, 'category' is ambiguous, and the description does not compensate for the schema gaps by offering any hints about parameter syntax, defaults, or usage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description starts with 'Search metadata extracted from the FortiAnalyzer API guide,' which clearly states a specific verb and resource. It also distinguishes itself from siblings by explicitly mentioning 'Use this before faz_raw_get or when a high-level tool does not cover an endpoint' and listing the types of results returned.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit guidance is provided: 'Use this before faz_raw_get or when a high-level tool does not cover an endpoint.' This gives clear when-to-use scenarios and names an alternative (faz_raw_get) as well as a general category of alternatives (high-level tools). The instruction to 'consult the linked source page for exact request parameters' further guides usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Run a bounded LogView submit/poll/fetch/cleanup workflow.
This convenience tool returns one result page and always attempts to delete its server-side task on completion, timeout, or error. Failed cleanup stays tracked for a shutdown retry. For manual pagination, use faz_start_log_search and faz_get_log_search instead.
| Name | Required | Description | Default |
|---|---|---|---|
| adom | No | ||
| limit | No | ||
| offset | No | ||
| devices | Yes | ||
| end_time | No | ||
| log_type | No | traffic | |
| max_logs | No | ||
| start_time | No | ||
| time_order | No | desc | |
| last_n_hours | No | ||
| case_sensitive | No | ||
| timeout_seconds | No | ||
| filter_expression | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses the cleanup behavior ('always attempts to delete its server-side task on completion, timeout, or error') and the failure handling ('stays tracked for a shutdown retry'). This goes beyond the annotations, which do not mention cleanup specifics, and adds valuable insight into the tool's side effects. No contradiction with annotations is present.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the core purpose, and every sentence adds value. It avoids fluff and clearly contrasts with alternatives, making it highly concise and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the workflow, return limitation, and cleanup behavior, but it lacks parameter semantics, which is a major gap for a tool with 13 parameters. The output schema and annotations provide some context, but the description itself is incomplete for effective use without additional parameter guidance.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description provides no parameter explanations. With 13 parameters, the agent must infer from schema titles and defaults only, which is insufficient for complex fields like 'filter_expression' or 'last_n_hours'. The description fails to compensate for the lack of schema documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool 'Run a bounded LogView submit/poll/fetch/cleanup workflow' and specifies it returns one result page, distinguishing it from manual pagination tools. It names the resource (LogView logs) and the specific convenience behavior, making its purpose unmistakable, especially relative to siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly says 'For manual pagination, use faz_start_log_search and faz_get_log_search instead,' which is a clear alternative. It also implies the tool is for a single page and handles cleanup automatically, giving the agent context on when to choose it over the manual tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Start an asynchronous LogView search and return its task ID.
Device names are explicit; use ["All_FortiGate"] only intentionally. Supply start_time and end_time together for an absolute appliance-local range, otherwise last_n_hours is used. Call faz_get_log_search next.
| Name | Required | Description | Default |
|---|---|---|---|
| adom | No | ||
| devices | Yes | ||
| end_time | No | ||
| log_type | No | traffic | |
| max_logs | No | ||
| start_time | No | ||
| time_order | No | desc | |
| last_n_hours | No | ||
| case_sensitive | No | ||
| filter_expression | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations include readOnlyHint=false and openWorldHint=true; the description adds that the operation is asynchronous, returns a task ID that must be polled later, and warns that using All_FortiGate can be resource-intensive. This goes beyond the annotations without contradicting them. It doesn't mention rate limits or required permissions, but those are not essential here.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, front-loaded with the core purpose, and each sentence earns its place. The structure efficiently conveys the async contract, time-range modes, device caution, and the required follow-up action with zero waste.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has an output schema, so return values need not be described. The description covers the async contract, next step (faz_get_log_search), and key parameter interactions. It leaves adom context and cancellation behavior to sibling tools and schema, which is a minor gap for full self-sufficiency.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 10 parameters with 0% description coverage. The description partially compensates by clarifying the mutual exclusion between start_time/end_time and last_n_hours, and by explaining the device list and All_FortiGate specialness. However, it does not explain adom, filter_expression syntax, time format, or the meaning of log_type/time_order beyond what the schema's enum/default values already show.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description opens with 'Start an asynchronous LogView search and return its task ID' – a specific verb, resource, and return contract. This clearly distinguishes it from sibling faz_get_log_search (retrieves results) and faz_search_logs (likely synchronous) by emphasizing the async and ID-returning nature.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit usage conditions: device names must be explicit, All_FortiGate is discouraged unless intentional, and start_time/end_time must be supplied together or last_n_hours is used. It also names the next step, 'Call faz_get_log_search next'. It does not explicitly say when to prefer this over faz_search_logs, but the async workflow is clearly implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0faz_cancel_log_searchfaz_connection_infofaz_get_adomfaz_get_log_searchfaz_get_system_performancefaz_get_system_statusfaz_list_adomsfaz_list_alertsfaz_list_devicesfaz_list_event_handlersfaz_list_log_forwardersfaz_list_report_layoutsfaz_list_report_schedulesfaz_list_report_templatesfaz_list_unregistered_devicesfaz_raw_getfaz_search_api_docsfaz_search_logsfaz_start_log_searchScored across 19 tools
Each tool targets a distinct resource or lifecycle stage: list/get for different entity types, start/get/cancel/search for log search, and status vs performance are clearly separated. Even the raw_get fallback is distinct from high-level tools, and search_api_docs is unique. The only near-overlap (search_logs vs start+get) is clearly differentiated by description.
Names consistently follow faz_<verb>_<noun> pattern for almost all tools (list_*, get_*, start_*, search_*). The lone outlier is faz_connection_info, which is a noun phrase rather than a verb phrase, and faz_raw_get mixes an adjective before the verb. Overall the pattern is highly predictable with minor deviations.
19 tools is on the heavier side but appropriate for a comprehensive FortiAnalyzer management interface covering system, ADOMs, devices, alerts, reports, logs, and a raw API fallback. The count feels slightly above the ideal 3-15 range, but each tool serves a distinct function and nothing feels redundant.
The tool set covers a broad read-only surface: system status/perf, ADOM listing/getting, device listing (registered and unregistered), alerts, event handlers, reports (layouts/templates/schedules), log search with full lifecycle, and a raw read endpoint for uncovered paths. Missing write operations and per-item get-by-ID are notable but align with the apparent read/query purpose; the raw_get gap-filler increases completeness.
Remote MCP for 1,500+ APIs. Vault-managed credentials; OAuth or API key. Search, load, and execute.
Access Avalara AvaTax API for tax calculation, transactions, nexus management, and compliance
Wrapper for the official Projuris ADV REST API (legal practice management): cases, people (clients/p
Search, document and execute authenticated API calls across 700+ apps via one MCP server
