The Vivado MCP server provides a structured automation interface for AMD Vivado FPGA design tools, enabling programmatic control of sessions, project management, design flows, reporting, and hardware debugging — without GUI click automation.
Installation & Session Management
Check local Vivado installations and retrieve versions
Start, stop, list, and manage persistent Vivado Tcl/GUI sessions with configurable capability profiles (safe, trusted-local, unrestricted)
Retrieve current session state
Tcl Scripting (trusted-local / unrestricted profiles)
Execute raw Tcl commands inline within a managed session
Source external Tcl script files into a managed session
Project Management
Create new Vivado Project Mode projects (with optional part/board targeting)
Open existing .xpr projects
Add RTL/HDL source and constraint (XDC) files, with optional top-module assignment
Retrieve structured project metadata: files, runs, IP cores, and block designs
Design Flow Automation
Launch and monitor synthesis runs
Launch and monitor implementation runs
Generate bitstreams via write_bitstream
Reporting
Generate reports: timing summary, timing paths, utilization, DRC, power, clock interaction, and messages
Artifact Management
List and read artifacts (logs, reports, snapshots) produced during a managed session
Help & Skills
Access built-in help topics and skill documents for Vivado workflows
Get AI-oriented suggestions for next steps based on current goal, session state, or last error
Hardware Debugging (read-only, requires explicit confirmation)
Read VIO (Virtual Input/Output) probe values
Capture ILA (Integrated Logic Analyzer) data
Read SPI registers via VIO
Allows AI agents to operate AMD Vivado through workflow-level tools, including managing Tcl sessions, creating/opening projects, adding sources, running synthesis, implementation, bitstream generation, and generating reports.
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., "@Vivado MCP Check Vivado installation and start a GUI session."
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.
Vivado CLI is a CLI-first automation layer for AMD Vivado. It keeps Vivado's
native Tcl as the execution layer, adds persistent session artifacts and
structured JSON output. MCP support has been removed; the product boundary is
now the vivado-cli command and the Vivado Tcl bridge.
The first design target is not GUI click automation. The preferred interactive
mode is a managed Vivado Tcl session that can open the GUI with start_gui,
load a small Tcl bridge, and let vivado-cli submit audited Tcl command files
into that same Vivado process. Batch mode remains useful for CI and fallback
automation.
Current design documents:
Discover a local Vivado installation and report its version.
Start and stop a managed Vivado Tcl/GUI session.
Verify whether a requested GUI session has a visible Vivado window without stealing focus, and bring that window forward only when explicitly requested.
Submit raw Tcl to a managed session when trusted-local expert mode is enabled.
Create or open project-mode Vivado projects.
Add RTL/source/constraint files with path validation.
Audit and manage Vivado filesets (sources / simulation / constraint sets) including include directories, defines, libraries, file properties, top module, USED_IN scopes, dry-run plans, and XDC reorder suggestions.
Apply structured source-fileset and constraint-set changes with optional before/after state diffs.
Audit XDC constraint filesets: loading order, per-file command markers, USED_IN scopes, methodology markers, and basic UG903/UG949 sanity warnings.
Search, dry-run/create, inspect, check upgrade state, upgrade, and generate output products for Vivado project IP.
Audit simulation setup, dry-run/prepare simulation filesets, launch Vivado simulation, and parse xsim/xelab/xvlog/xvhdl logs into issue IDs.
Create, inspect, audit, dry-run/mutate, validate, and generate generic IP Integrator block designs.
Run synthesis, implementation, and bitstream generation.
Run Non-project Mode flows with audit/dry-run support: read RTL/XDC, check prerequisites, execute synth/opt/place/route, write checkpoints, and collect reports.
Generate timing, utilization, DRC, methodology, power, CDC, bus-skew, clock-interaction, and message reports.
Parse common report outputs into structured summaries and aggregate report diagnostics with issue IDs, root-cause hints, quality gates, next-action plans, and official-document queries.
Perform explicit hardware access for hw_server targets/devices, debug core/probe discovery, VIO probe readback, generic ILA capture/CSV analysis, and VIO-backed SPI register readback; hardware programming remains out of scope for structured commands.
Capture JSON state snapshots and diff project/fileset/constraint/IP/BD/run/report state before and after risky or long-running operations.
Store logs and generated reports as session artifacts.
Provide built-in help/skills so AI or human CLI callers can learn the intended Vivado workflows before acting.
Package AMD official Vivado documentation metadata and topic guidance as the authority layer for help and expert Tcl planning.
Related MCP server: MCP for Vivado
safe: workflow tools only; no raw Tcl.
trusted-local: workflow tools plus raw Tcl/source-file execution inside the managed Vivado session.
unrestricted: raw Tcl with minimal policy checks for personal local use.
The packaged bridge in src/vivado_cli/assets/cli_bridge.tcl is the core control path: vivado-cli submits Tcl files to a live Vivado Tcl/GUI session and receives result files back.
The CLI exposes tutorial and authority content through JSON commands:
vivado-cli help topic <topic>
vivado-cli assist next --goal "<task>"
vivado-cli skills list
vivado-cli skills get <skill_id>
vivado-cli tools list
vivado-cli tools describe <command-or-tool-id>
vivado-cli tcl help <command>
vivado-cli tcl review --file <script.tcl>
Seed skill docs live in docs/skills.
The official reference layer stores document IDs, AMD URLs, scope summaries, topic routing, and local filename candidates. It does not copy the full AMD document text into this repository.
From a fresh clone:
git clone https://github.com/Shanqianlvshui/Vivado_CLI.git
cd Vivado_CLI
python -m venv .venv
.\.venv\Scripts\python.exe -m pip install -e ".[dev]"Basic smoke checks after installation:
.\.venv\Scripts\vivado-cli.exe --help
.\.venv\Scripts\vivado-cli.exe tools list
.\.venv\Scripts\vivado-cli.exe tcl help create_clockThis machine has been tested with:
C:\AMDDesignTools\2025.2.1\Vivado\bin\vivado.bat
C:\Xilinx\Vivado\2023.1\bin\vivado.batVivado discovery checks, in order: explicit --vivado-path, VIVADO_BIN
(including persisted Windows user/machine environment variables), vivado on
PATH, then common Windows installs such as C:\AMDDesignTools,
C:\AMD\Vivado, and C:\Xilinx\Vivado. Common installs are sorted newest
version first.
The stable local entry point for agents and external tools is:
C:\Tools\vivado-cli\bin\vivado-cli.exeNew terminals can also read the full path from:
$env:VIVADO_CLI_EXETo verify the published repository from scratch, run:
powershell -ExecutionPolicy Bypass -File .\scripts\verify-cold-clone.ps1The default smoke path clones https://github.com/Shanqianlvshui/Vivado_CLI.git,
installs the editable package in a temporary virtual environment, runs CLI help
and tool-discovery checks, compiles src and tests, and runs the fast
fake-Vivado smoke tests. Add -Full to run the full unit suite in the cold
clone.
vivado-cli is the primary entry point. It writes persistent session records
under .vivado_cli/sessions, so separate CLI invocations can operate the same
live Vivado process.
vivado-cli check-installation
vivado-cli check-installation --vivado-path C:\AMDDesignTools\2025.2.1\Vivado\bin\vivado.bat
vivado-cli --workspace C:\Workspace\Vivado_mcp session start `
--vivado-path C:\AMDDesignTools\2025.2.1\Vivado\bin\vivado.bat
vivado-cli --workspace C:\Workspace\Vivado_mcp session recovery `
--session <session_ref>
vivado-cli --workspace C:\Workspace\Vivado_mcp session timeline `
--session <session_ref> `
--limit 20
vivado-cli --workspace C:\Workspace\Vivado_mcp session artifacts `
--session <session_ref> `
--kind report `
--limit 10
vivado-cli --workspace C:\Workspace\Vivado_mcp session read-artifact `
--session <session_ref> `
reports\timing_summary.rpt `
--max-chars 12000
vivado-cli --workspace C:\Workspace\Vivado_mcp session open-project `
--session <session_ref> `
C:\Workspace\Vivado\XCZU19EG\XCZU19EG_TEST\projects\qt7331_adda_2023.1\qt7331_adda_2023.1.xpr
vivado-cli --workspace C:\Workspace\Vivado_mcp bd summary `
--session <session_ref> `
--design jesd204b_bd `
--validate
vivado-cli --workspace C:\Workspace\Vivado_mcp run status `
--session <session_ref> `
--run synth_1
vivado-cli --workspace C:\Workspace\Vivado_mcp run progress `
--session <session_ref> `
--tail 20 `
impl_1
vivado-cli --workspace C:\Workspace\Vivado_mcp run launch `
--session <session_ref> `
synth_1 `
--jobs 8
vivado-cli --workspace C:\Workspace\Vivado_mcp run launch-local `
--session <session_ref> `
--jobs 8 `
synth_1
vivado-cli --workspace C:\Workspace\Vivado_mcp run diagnose `
--session <session_ref> `
synth_1
vivado-cli --workspace C:\Workspace\Vivado_mcp run logs `
--session <session_ref> `
synth_1 `
--tail 80
vivado-cli --workspace C:\Workspace\Vivado_mcp run reset `
--session <session_ref> `
synth_1 `
--include-stale-dependencies `
--expect-destructive
vivado-cli --workspace C:\Workspace\Vivado_mcp report `
--session <session_ref> `
cdc
vivado-cli --workspace C:\Workspace\Vivado_mcp report `
--session <session_ref> `
bus_skew
vivado-cli --workspace C:\Workspace\Vivado_mcp hw list-debug-cores `
--session <session_ref> `
--expect-hardware-access
vivado-cli --workspace C:\Workspace\Vivado_mcp hw vio-read `
--session <session_ref> `
--vio hw_vio_0 `
--probe chip_config/spi_read_status `
--probe chip_config/spi_read_req `
--expect-hardware-access
vivado-cli --workspace C:\Workspace\Vivado_mcp hw vio-write `
--session <session_ref> `
--vio hw_vio_0 `
--set chip_config/spi_read_req=0 `
--expect-hardware-access `
--expect-vio-write
vivado-cli --workspace C:\Workspace\Vivado_mcp hw capture-ila `
--session <session_ref> `
--ila hw_ila_0 `
--depth 1024 `
--analysis adc14 `
--sample-rate-hz 312500000 `
--label bringup_capture `
--expect-hardware-access
vivado-cli --workspace C:\Workspace\Vivado_mcp hw spi-read `
--session <session_ref> `
--vio hw_vio_0 `
--status-probe spi/status `
--req-probe spi/req `
--target-probe spi/target `
--addr-probe spi/addr `
--reg 2:0x0281 `
--reg 2:0x0300 `
--expect-hardware-access
vivado-cli --workspace C:\Workspace\Vivado_mcp tcl review `
--file .\scripts\change_bd.tcl
vivado-cli --workspace C:\Workspace\Vivado_mcp session run-tcl `
--session <session_ref> `
--file .\scripts\change_bd.tcl `
--expect-destructiveThe run status and run progress responses expose needs_refresh,
is_current, and is_stale. A Vivado status containing Complete is
not treated as reusable when the run is stale.
VIVADO_CLI_WORKSPACE is the default workspace for managed sessions.
VIVADO_CLI_ALLOWED_ROOTS is a semicolon-separated list on Windows; workflow
paths such as projects, sources, constraints, and Tcl files in trusted-local
mode must stay under one of these roots. VIVADO_CLI_DOCS_ROOT points to the
local AMD Vivado documentation library used by the official-reference index; it
defaults to C:\Database\domains\fpga\xilinx\vivado\docs\raw. Set
VIVADO_CLI_PDFTOTEXT if pdftotext is not on PATH.
CLI callers should use this order:
Start with vivado-cli assist next --goal "<task>" and include --session, --last-error, or a Tcl draft with --tcl / --file when available.
Discover the available surface with vivado-cli tools list, vivado-cli tools describe <command>, vivado-cli skills list, and vivado-cli skills get <skill_id>.
Use vivado-cli tcl help <command> before unfamiliar Vivado Tcl; it combines official-document search, CLI coverage guidance, and optional installed Vivado help when a session is attached.
Use structured commands first: project summary, fileset ..., constraint ..., bd ..., run ..., report, and hw ....
Use vivado-cli tcl review before raw expert Tcl, then vivado-cli session run-tcl or vivado-cli session source-tcl only when no structured command covers the task.
Pass explicit acknowledgements for risky actions, such as --expect-destructive, --expect-hardware-access, and --expect-vio-write.
Read state_tracking and state_diff from mutating fileset/constraint commands before launching long runs or handing the session to another agent.
For a resumed or stale thread, run vivado-cli session recovery, then inspect session timeline, session artifacts, or session read-artifact before changing Vivado state.
After mutating project state, refresh with vivado-cli project summary, vivado-cli fileset describe, vivado-cli constraint check-order, vivado-cli bd summary, or vivado-cli run diagnose as appropriate.
Use this sequence:
vivado-cli help topic gui-session
vivado-cli tools list
vivado-cli check-installation
vivado-cli session start
vivado-cli session state --session <session_ref>
vivado-cli tcl help create_project
vivado-cli tcl review --tcl "return \"version=[version -short]\""
vivado-cli session run-tcl --session <session_ref> --tcl "return \"version=[version -short]\""
vivado-cli project summary --session <session_ref> after opening or creating a project
vivado-cli session stop --session <session_ref>
Use vivado-cli tools list as the source of truth. The current top-level
groups are:
check-installation
session start|adopt|list|state|artifacts|timeline|read-artifact|recovery|open-project|run-tcl|source-tcl|stop
tcl help|review
skills list|get
help topic
assist next
tools list|describe
project summary
fileset list|describe|create|add-files|remove-files|set-file-properties|set-top|apply
constraint diagnostics|check-order|apply
bd summary|validate
run status|progress|launch|launch-local|logs|diagnose|reset
report
hw list-debug-cores|vio-read|vio-write|capture-ila|spi-read
.\.venv\Scripts\python.exe -m compileall -q src tests
.\.venv\Scripts\python.exe -m pytest tests\unit -qThe test suite includes a fake Vivado process and CLI lifecycle tests. GitHub
Actions runs the same package install, compile check, CLI smoke, and full unit
suite on windows-latest.
Command files, result files, logs, and reports are stored under the managed session directory and exposed through artifact URIs:
vivado://sessions/{session_ref}/artifacts/{artifact_id}Use vivado-cli session artifacts --session <session_ref> to list artifact IDs
and vivado-cli session read-artifact --session <session_ref> <artifact_id> to
read a bounded text slice. vivado-cli session recovery --session <session_ref>
returns the latest analyses, snapshots, quality gates, timeline preview, and
next CLI actions for AI handoff and long-running task recovery.
Commands that generate reports, summaries, captures, snapshots, or diffs return
filesystem paths and vivado://... artifact URIs in their JSON output.
Structured fileset and constraint mutations attach state_tracking and
state_diff by default; pass --no-state-diff only for intentional bulk edits
where speed matters more than immediate audit artifacts.
Use vivado-cli tcl help <command> for Tcl command routing. It searches the
local AMD/Xilinx documentation library when available, reports the official-doc
topic, shows any structured CLI coverage for that command family, and can also
query installed Vivado help when --session <session_ref> is supplied.
The CLI uses the local PDF library under
C:\Database\domains\fpga\xilinx\vivado\docs\raw by default. Set
VIVADO_CLI_DOCS_ROOT to another documentation root and VIVADO_CLI_PDFTOTEXT
if pdftotext is not on PATH.
GUI click automation.
Attaching to an arbitrary already-open Vivado process that did not load the CLI bridge.
Hardware programming, configuration-memory writes, boot operations, and debug/probe mutation. Read-only hardware discovery is supported with explicit confirmation.
Advanced IP Integrator automation beyond the generic BD action model.
Add RTL/source and constraint files to the current Vivado project.
| Name | Required | Description | Default |
|---|---|---|---|
| session_ref | Yes | ||
| sources | No | ||
| constraints | No | ||
| top | No | ||
| timeout_seconds | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description bears full burden. It only states the basic function without disclosing behavioral traits like whether files are merged or overwritten, permission requirements, or what happens on error. The description is too minimal for a mutation 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 a single sentence with no wasted words, but it is too terse for the tool's complexity (5 parameters, no annotations). A slightly longer description with structured details would be more helpful.
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 absence of annotations, 5 parameters, and an output schema (not shown), the description is incomplete. It does not explain what the tool returns or any side effects on the project. The description provides only the bare minimum of context.
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 only mentions 'RTL/source and constraint files', which loosely maps to the sources and constraints parameters, but offers no detail on session_ref (required), top, or timeout_seconds. The description fails to add meaningful context beyond the parameter titles.
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 ('Add'), the resource type ('RTL/source and constraint files'), and the target ('current Vivado project'). It effectively distinguishes from sibling tools like vivado_create_project and vivado_open_project.
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 on when to use this tool versus alternatives (e.g., vivado_run_tcl for custom operations), no prerequisites mentioned (e.g., an existing active session), and no exclusion criteria provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Find Vivado and return its version.
| Name | Required | Description | Default |
|---|---|---|---|
| vivado_path | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry full burden. It only states 'Find Vivado and return its version' without disclosing what happens if Vivado is not found, how it locates the installation, or any side effects. This is insufficient for an agent to understand expected behavior.
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 very short (one sentence) and front-loaded, but it sacrifices detail for brevity. It could be longer to cover essential information without being verbose. Score reflects adequate conciseness but insufficient completeness.
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 that there is an output schema, the description could be shorter, but it still fails to mention what the output contains (e.g., version string), error cases, or whether the tool searches common paths. It is incomplete for a simple check tool.
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 coverage is 0%, meaning no parameter descriptions in the schema. The description does not explain the 'vivado_path' parameter at all, beyond what the schema provides (type and default). An agent has no guidance on what value to provide or its purpose.
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 'Find' and the resource 'Vivado' and its version. This distinguishes it from sibling tools like vivado_create_project or vivado_run_synthesis, which are about project creation or running tasks. The purpose is 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 gives no explicit guidance on when to use this tool vs alternatives. However, its name and simple purpose imply it's for checking if Vivado is installed and retrieving its version. It lacks instructions on prerequisites or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a Vivado Project Mode project in the managed session.
| Name | Required | Description | Default |
|---|---|---|---|
| session_ref | Yes | ||
| project_name | Yes | ||
| project_dir | Yes | ||
| part | No | ||
| board_part | No | ||
| force | No | ||
| timeout_seconds | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavioral traits but only says 'in the managed session', which is vague. It doesn't mention side effects, whether it requires an active session, default behaviors (e.g., handling existing projects), or the meaning of the 'force' 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 very concise (12 words), but it is under-specified for a tool with 7 parameters. Conciseness should not come at the cost of missing essential details; a longer description with key parameter clarifications would be more helpful.
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 complexity (7 parameters, output schema exists), the description is severely incomplete. It does not explain what 'Project Mode' means, what the output contains, or any prerequisites. The output schema is mentioned in signals but not referenced in the description to aid understanding.
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 by explaining key parameters. However, it adds no information beyond the parameter names. The parameters like 'part', 'board_part', 'force' are not explained, leaving the agent to guess 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 clearly states the action 'Create' and the resource 'Vivado Project Mode project', with context 'in the managed session'. This distinguishes it from siblings like vivado_open_project (opens existing) and vivado_start_session (starts session). However, it lacks specificity about what 'Project Mode' entails compared to other modes.
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 no guidance on when to use this tool versus alternatives like vivado_open_project, vivado_start_session, or vivado_source_tcl. It does not mention prerequisites (e.g., an active session) or scenarios where this tool is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Run implementation through write_bitstream.
| Name | Required | Description | Default |
|---|---|---|---|
| session_ref | Yes | ||
| run_name | No | impl_1 | |
| jobs | No | ||
| timeout_seconds | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must cover behavior. It states the action but omits side effects (e.g., file writes), resource usage (e.g., time, disk), or whether it modifies the project. The timeout parameter hints at long duration but this is not disclosed.
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 extremely brief (4 words) but at the expense of essential information. It is not well-structured for usability; a slightly longer description with key details would improve it.
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?
Despite having an output schema, the description does not explain return values or success conditions. For a 4-parameter tool with no annotation support, the description lacks critical context for correct invocation.
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 coverage is 0%; the description adds no meaning to any of the 4 parameters (session_ref, run_name, jobs, timeout_seconds). The agent must infer their purpose from names alone, which is insufficient.
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 'Run implementation through write_bitstream' clearly specifies the tool performs implementation and bitstream generation, distinguishing it from siblings like vivado_run_implementation which only runs implementation. However, it could be more explicit about the composite 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?
No guidance on when to use this tool versus alternatives like vivado_run_implementation or prerequisites. An agent has no context on whether synthesis must precede this step or what scenarios avoid using this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return one built-in Vivado MCP skill document.
| Name | Required | Description | Default |
|---|---|---|---|
| skill_id | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description should disclose behavioral details. It only states the return type but does not mention potential errors, idempotency, or required state (e.g., valid skill_id).
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 very concise (one sentence) but lacks structure such as examples or additional context. It is not overly verbose, but brevity compromises completeness.
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 presence of an output schema, the description could be minimal if the schema were self-explanatory. However, schema coverage is 0% and no annotations exist, so the description fails to provide sufficient context for correct usage.
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 sole parameter 'skill_id' has no description in the schema (0% coverage). The description does not explain what a skill_id is, how to obtain it, or its format, adding no value beyond the schema.
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 ('Return') and the resource ('one built-in Vivado MCP skill document'). It effectively distinguishes from sibling tool 'vivado_list_skills' which would list all skills.
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 on when to use this tool versus alternatives (e.g., vivado_list_skills). No prerequisites or conditions for invocation are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return concise help for a Vivado MCP topic.
| Name | Required | Description | Default |
|---|---|---|---|
| topic | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavioral traits. It only says 'concise help' but does not explain what that entails (e.g., synchronous, cached, source of information). This is insufficient for safe invocation.
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 fluff, but it is too minimal to be considered well-structured. It sacrifices necessary detail for brevity, resulting in a borderline score.
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 low complexity, the description should at least note that an output schema exists or mention the nature of the help (e.g., text, list). The omission of such details makes the tool incomplete for an agent.
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 coverage is 0%, meaning the parameter description in the schema is just the title. The tool description adds no meaning or examples for the 'topic' parameter, leaving the agent without guidance on valid values or format.
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 it returns concise help for a Vivado MCP topic, using a specific verb and resource. While clear, it does not differentiate from sibling tools like vivado_get_skill which also provide help-like information.
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 on when to use this tool versus alternatives such as vivado_get_skill or vivado_suggest_next_steps. There is no context on prerequisites or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List files produced in a managed session directory.
| Name | Required | Description | Default |
|---|---|---|---|
| session_ref | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden. It does not disclose read-only nature, side effects, or required permissions. The single sentence only states the basic function, leaving behavioral traits unaddressed.
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 extremely short (one sentence) with no wasted words, but it is under-specified. It is concise but lacks structure to convey essential information such as parameter details or output format.
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 presence of an output schema, the description need not detail return values, but it fails to provide sufficient context about 'artifacts', the session requirement, or how listing works. The description is incomplete for effective tool selection and invocation.
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 offers no explanation of the 'session_ref' parameter beyond its type and requirement. The description fails to add any value over the schema, leaving the parameter meaning ambiguous.
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 lists files (artifacts) in a managed session directory. It distinguishes from siblings like vivado_list_sessions and vivado_read_artifact by specifying 'artifacts' rather than sessions or reading. However, it lacks detail on what constitutes an artifact (e.g., file types, 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?
No explicit guidance on when to use this tool versus alternatives. There is no mention of prerequisites (e.g., a session must exist) or when not to use it. The context must be inferred from the sibling names.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List active managed Vivado sessions.
| 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?
No annotations provided, so description carries full burden. It only states the action (list) and resource, but does not disclose side effects, authentication needs, or any behavioral traits beyond the basic read operation.
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?
Single sentence of 5 words, front-loaded with verb and resource, no 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 list tool with no parameters and an output schema, the description is minimally adequate but lacks context on what constitutes 'active managed' sessions or how the output is structured beyond the 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?
With zero parameters and 100% schema coverage, the description adds value by naming the resource, meeting the baseline for no-parameter tools.
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 specific verb 'list' and resource 'active managed Vivado sessions', clearly distinguishing from sibling tools like vivado_start_session, vivado_stop_session, and vivado_session_state.
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 explicit guidance on when to use this tool vs alternatives, but the purpose is clear enough that usage context is implied. Could benefit from mentioning when not to use or suggesting alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List built-in Vivado MCP skills.
| Name | Required | Description | Default |
|---|---|---|---|
| query | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must disclose behavioral traits. It only says 'list', implying a read operation, but does not explicitly state it is non-destructive, idempotent, or any safety characteristics.
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 too brief, omitting important details like parameter behavior, making it less effective than a slightly longer but more informative description.
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?
While an output schema exists (reducing need for return value explanation), the description lacks context about the query parameter and any behavioral notes. For a simple list tool, it is under-specified.
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 one parameter 'query' (optional string or null) with no description. The tool description does not explain the purpose or effect of this parameter, leaving its semantics entirely unclear.
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 lists built-in Vivado MCP skills, using a specific verb and resource. Among siblings like vivado_get_skill (retrieves one skill) and vivado_list_artifacts, this distinction is clear.
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 like vivado_get_skill. The description does not mention any context, prerequisites, or when-not-to-use scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Open an existing Vivado project in the managed session.
| Name | Required | Description | Default |
|---|---|---|---|
| session_ref | Yes | ||
| project_path | Yes | ||
| timeout_seconds | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description must disclose behavioral traits. It only states 'Open an existing Vivado project', omitting any side effects, resource locking, or session implications. The agent gets no sense of whether this is a read-only operation or if it alters 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?
Single sentence of 10 words is very concise. However, it sacrifices necessary detail for brevity, making it slightly under-informative. Still, it is front-loaded and to the point.
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 context (3 parameters, output schema exists, many siblings), the description is too sparse. It lacks usage context, parameter details, and behavioral notes, leaving the agent with minimal guidance for correct invocation.
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%, yet the description adds no meaning to any of the 3 parameters (session_ref, project_path, timeout_seconds). The agent learns nothing about their purpose, format, or constraints beyond the bare schema.
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 ('Open') and the resource ('existing Vivado project'), distinguishing it from siblings like vivado_create_project. The phrase 'in the managed session' adds specific context without ambiguity.
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 on when to use this tool versus alternatives such as vivado_create_project or vivado_add_sources. The description does not mention preconditions or scenarios where opening a project is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return structured information about the current Vivado project, files, runs, IP, and block designs.
| Name | Required | Description | Default |
|---|---|---|---|
| session_ref | Yes | ||
| timeout_seconds | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must carry the burden of behavioral disclosure. It implies a read-only operation ('Return structured information'), but does not mention side effects, permissions, or dependencies like needing an open project. The timeout parameter hints at potential duration, but no explicit behavior is described.
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, which is concise but vague. It lists components but lacks detail. It could be more informative without becoming verbose, such as mentioning the output format or required project state.
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 existence of an output schema, explanation of return values is not needed. However, the description misses key context: it does not state that the tool requires an active session or project, nor does it explain what 'structured information' entails. This inadequacy for a tool with 2 parameters and no annotation coverage.
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. However, it does not explain the parameters: session_ref (required, likely a session identifier) and timeout_seconds (default 60). No additional meaning is added beyond the schema, leaving their purpose unclear.
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 returns structured information about the Vivado project, listing specific aspects (files, runs, IP, block designs). It uses a specific verb ('Return') and resource, but does not explicitly differentiate from siblings like vivado_report or vivado_list_artifacts, limiting distinction.
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 such as vivado_report or vivado_list_artifacts. The description does not mention prerequisites (e.g., an active session) or exclusions, leaving the agent to infer usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read a text artifact from a managed session.
| Name | Required | Description | Default |
|---|---|---|---|
| session_ref | Yes | ||
| artifact_id | Yes | ||
| max_chars | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Description implies read-only behavior but lacks additional context such as error handling, rate limits, or authentication needs; no annotations to compensate, so transparency is minimal.
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?
Single sentence of 7 words, front-loaded with action, no redundant information; highly efficient.
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?
Despite output schema existence, description omits essential context such as how to obtain artifact_id or that session_ref must be from a previously started session; agent may lack full usage 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?
Schema description coverage is 0%, and the tool description provides no explanation of parameters like session_ref, artifact_id, or max_chars; agent must rely on parameter names alone.
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 clearly states 'Read a text artifact from a managed session', using specific verb and resource; contrasts with siblings like vivado_list_artifacts, establishing distinct 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?
No guidance on when to use this tool or when to prefer alternatives; no mention of prerequisites (e.g., need for valid session_ref) or relationship to list tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Generate a Vivado report in the managed session.
| Name | Required | Description | Default |
|---|---|---|---|
| session_ref | Yes | ||
| report_type | Yes | ||
| output_name | No | ||
| timeout_seconds | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description lacks behavioral details. It does not disclose whether the operation is read-only, if it modifies session state, or any side effects. With no annotations, the description carries the full burden but fails to provide transparency.
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 wasted words, but it is under-informative for a tool with 4 parameters. It front-loads the purpose but lacks necessary detail.
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 complexity (4 parameters, output schema, no annotations), the description is incomplete. It does not explain the session concept, the role of session_ref, the report_type options, or the output format, leaving the agent to infer from the schema alone.
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 0% description coverage for parameters, and the tool description does not mention any parameters or their semantics. It provides no additional meaning beyond the schema's type and enum definitions.
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 verb 'Generate' and resource 'Vivado report' within the context of a 'managed session'. It distinguishes from sibling tools as no other tool explicitly generates a report, but it could be more specific about the report types supported.
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. It does not mention prerequisites, such as requiring a session or specific project state, nor does it differentiate from similar tools like vivado_run_tcl.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Launch and wait for a Vivado implementation run.
| Name | Required | Description | Default |
|---|---|---|---|
| session_ref | Yes | ||
| run_name | No | impl_1 | |
| jobs | No | ||
| timeout_seconds | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description must disclose behavioral traits. It mentions 'wait' (implying blocking) but fails to describe timeout behavior, resource usage, potential side effects, or that synthesis must precede implementation. The description is insufficient.
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 extremely short (one sentence) but sacrifices necessary detail for conciseness. It does not efficiently convey information beyond the tool's core purpose.
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 4 parameters, no annotations, and an output schema (not shown), the description is severely incomplete. It omits prerequisites (e.g., prior synthesis), parameter roles, behavioral implications, and output format, making it inadequate for safe agent invocation.
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% (no parameter descriptions) and the tool description adds no explanation of any of the four parameters (session_ref, run_name, jobs, timeout_seconds). The agent cannot understand parameter meanings or defaults from the description.
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-resource pair ('Launch and wait for a Vivado implementation run'), clearly distinguishing it from sibling tools like vivado_run_synthesis and vivado_generate_bitstream.
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 such as vivado_run_synthesis or vivado_generate_bitstream. There is no mention of prerequisites or context for invocation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Launch and wait for a Vivado synthesis run.
| Name | Required | Description | Default |
|---|---|---|---|
| session_ref | Yes | ||
| run_name | No | synth_1 | |
| jobs | No | ||
| timeout_seconds | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description only says 'launch and wait', omitting important behavioral details such as failure modes, side effects, locking, or timeout behavior. Annotations are absent, so the description carries the full burden of disclosure.
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 very concise but at the expense of missing critical information. It could be slightly longer to include parameter roles or behavioral notes without becoming verbose.
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 (4 parameters, no annotations), the description is woefully incomplete. It ignores the existence of an output schema and fails to explain parameter semantics or usage context.
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 adds no meaning to the parameters. The schema provides default values and types but no further context. Parameters like 'jobs' and 'timeout_seconds' are left completely unexplained.
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 ('launch and wait') and the resource ('Vivado synthesis run'), which is a well-defined concept in the Vivado context. It effectively distinguishes from sibling tools like vivado_run_implementation and vivado_generate_bitstream.
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 no guidance on when to use this tool vs alternatives. It does not mention prerequisites (e.g., open project) or situations where it should not be used.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Run raw Tcl in a managed session. Requires trusted-local or unrestricted profile.
| Name | Required | Description | Default |
|---|---|---|---|
| session_ref | Yes | ||
| tcl | Yes | ||
| timeout_seconds | No | ||
| expect_destructive | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It only mentions a profile requirement but does not disclose behavioral traits such as destructiveness, authorization needs, or side effects. The expect_destructive parameter hints at destructiveness but is not explained in the description.
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, very concise. It front-loads the main action. However, it may be too brief, sacrificing necessary detail.
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 has 4 parameters, no annotations, and an output schema, the description does not provide enough context. It omits return format, timeout behavior, and the meaning of expect_destructive. The output schema exists but is not described.
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 add meaning for all 4 parameters. However, the description provides no parameter-level detail. It does not explain session_ref, tcl, timeout_seconds, or expect_destructive.
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 tool's purpose: 'Run raw Tcl in a managed session.' It also specifies a profile requirement. However, it does not differentiate from sibling tools like vivado_source_tcl, which may have similar functionality.
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. The profile requirement is mentioned but does not serve as a usage guideline. No when-not-to-use or alternative tools are cited.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return current bridge/process state for a managed Vivado session.
| Name | Required | Description | Default |
|---|---|---|---|
| session_ref | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It mentions returning state but does not disclose whether the operation is safe, destructive, or requires special permissions. The term 'bridge/process state' is vague and does not clarify behavior beyond a simple read.
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, straightforward sentence with no filler. It is concise, though it could benefit from slightly more detail without becoming verbose.
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?
Despite having an output schema, the tool is simple and the description is minimal. For an agent to select and invoke it correctly, more context is needed about what 'state' values are possible, how they map to the session lifecycle, and how to interpret the output.
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% for the single required parameter 'session_ref'. The description does not explain what a session ref is, how to obtain it, or its format. The schema provides only the title and type, so the agent lacks essential context.
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 'return', the resource 'bridge/process state', and the context 'managed Vivado session'. It distinguishes from sibling tools like vivado_list_sessions which list sessions, while this retrieves state for a specific session.
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 such as vivado_list_sessions or vivado_start_session. There is no mention of prerequisites, when-not-to-use, or related tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Source a Tcl file in a managed session. Requires trusted-local or unrestricted profile.
| Name | Required | Description | Default |
|---|---|---|---|
| session_ref | Yes | ||
| script_path | Yes | ||
| tclargs | No | ||
| timeout_seconds | No | ||
| expect_destructive | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It mentions a security requirement but fails to disclose side effects, error behavior, return values, or destructiveness. The 'expect_destructive' parameter hints at potential issues, but the description does not address them.
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, no fluff. Front-loaded with purpose. Every word adds value.
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?
Despite having an output schema and 5 parameters, the description is extremely sparse. It does not explain what sourcing does, how timeout or destructive behavior are handled, or what output is returned. Incomplete for a tool with moderate complexity.
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 description must compensate. However, it does not describe any of the 5 parameters (session_ref, script_path, tclargs, timeout_seconds, expect_destructive). Only 'source a Tcl file' loosely maps to script_path, but no semantic detail beyond the schema.
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?
Clearly states the verb 'source' and the resource 'Tcl file in a managed session'. It distinguishes from sibling 'vivado_run_tcl' by specifying file sourcing rather than inline commands. The requirement 'trusted-local or unrestricted profile' adds context.
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?
Specifies a prerequisite (trusted-local or unrestricted profile) but lacks explicit guidance on when to use this tool vs alternatives like 'vivado_run_tcl'. No when-not or alternative tool references.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Start a managed Vivado Tcl session, optionally opening the GUI.
| Name | Required | Description | Default |
|---|---|---|---|
| vivado_path | No | ||
| workspace_dir | No | ||
| open_gui | No | ||
| capability_profile | No | trusted-local | |
| startup_timeout_seconds | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description carries the full burden. It only mentions starting a session and optionally opening GUI, but does not disclose what 'managed' entails, effects on existing sessions, or any safety considerations (e.g., destructive actions).
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, but it sacrifices detail for brevity. It could include more structured information without becoming verbose. Not excessively long, but insufficiently informative.
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 5 parameters, no annotations, no parameter descriptions, and an output schema not shown, the description is incomplete. It does not cover setup requirements, return value, or how it fits into the overall workflow with sibling tools.
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%, yet the description only hints at the open_gui parameter. It does not explain vivado_path, workspace_dir, capability_profile (e.g., meaning of 'safe' vs 'unrestricted'), or startup_timeout_seconds. The description adds minimal value beyond parameter names.
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 'Start' and resource 'managed Vivado Tcl session', and mentions the optional GUI. It distinguishes from sibling tools like vivado_run_tcl or vivado_stop_session, which handle different operations.
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 on when to use this tool compared to others, such as prerequisites (e.g., should it be used before running Tcl commands) or scenarios to avoid. The description lacks context for decision-making.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Stop a managed Vivado session.
| Name | Required | Description | Default |
|---|---|---|---|
| session_ref | Yes | ||
| force | No | ||
| timeout_seconds | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided; description only says 'stop'. Does not disclose effects of force parameter, timeout behavior, or consequences like unsaved data loss. Minimal behavioral disclosure.
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?
Single sentence is very concise, but it lacks necessary substance. It earns its place by being short, but not by being informative.
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 3 parameters, no schema descriptions, and no annotations, the description is severely inadequate. Does not mention prerequisites (e.g., session must exist), return values, or side effects.
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 coverage is 0% and description adds no information about parameters. Does not explain session_ref (how to obtain), force (what forcing does), or timeout_seconds (how it affects stopping).
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 clearly states the action (stop) and resource (managed Vivado session). It is unambiguous but lacks differentiation from sibling tools like vivado_session_state or vivado_start_session.
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 on when to use this tool versus alternatives (e.g., vivado_session_state to check state, vivado_start_session to start). No exclusions or prerequisites mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Suggest next MCP operations from current context.
| Name | Required | Description | Default |
|---|---|---|---|
| goal | No | ||
| last_error | No | ||
| session_ref | No | ||
| project_ref | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden for behavioral disclosure. It only states that the tool 'suggests' operations, without mentioning side effects, read-only status, or any impact on state. The behavioral traits remain opaque.
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, which is concise. However, it lacks structure and important details. While brevity is valued, it sacrifices necessary explanatory content, making it minimally adequate.
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 as a context-aware suggestion tool with 4 optional parameters and a diverse set of sibling tools, the description is incomplete. It does not explain how suggestions are generated, what output to expect (though output schema exists), or how to use the context parameters effectively.
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 adds no parameter details. The four optional parameters (goal, last_error, session_ref, project_ref) have self-explanatory titles but no further semantics. 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 'Suggest next MCP operations from current context' is vague. It identifies the tool as a suggestion engine but does not specify what kind of operations or how context is used. It is not a tautology but lacks specificity to distinguish from siblings like vivado_help or vivado_list_skills.
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 usage guidelines are provided. The description does not indicate when to use this tool over alternatives, when not to use it, or any prerequisites. The agent has no guidance on appropriate invocation context.
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.0vivado_add_sourcesvivado_check_installationvivado_create_projectvivado_generate_bitstreamvivado_get_skillvivado_helpvivado_list_artifactsvivado_list_sessionsvivado_list_skillsvivado_open_projectvivado_project_summaryvivado_read_artifactvivado_reportvivado_run_implementationvivado_run_synthesisvivado_run_tclvivado_session_statevivado_source_tclvivado_start_sessionvivado_stop_sessionvivado_suggest_next_stepsScored across 21 tools
Most tools have clearly distinct purposes, but there is minor overlap between vivado_run_tcl and vivado_source_tcl, which could cause confusion. Overall, agents can distinguish the tools well.
All tools follow a consistent snake_case pattern with 'vivado_' prefix and verb_noun structure, making predictions easy.
21 tools are well-scoped for a Vivado development server, covering project management, synthesis, implementation, bitstream generation, session management, and reporting without bloat.
The tool surface covers the standard FPGA design flow from project creation to bitstream generation, and includes session and TCL management. Missing simulation-related tools, but that may be out of scope.
A comprehensive Model Context Protocol (MCP) server that enables AI assistants to interact with yo…
A Model Context Protocol server for Wix AI tools
MCP server for progressive tool usage at any scale (see https://klavis.ai)
Enable secure connectivity between Sentry issues and debugging data, and LLM clients, using a Model Context Protocol (MCP) server.
