Tableau Workbook (.twb/.twbx) generation toolkit for reproducible dashboards and workbook engineering Programmatically create Tableau workbooks with stable analytical primitives, dashboard composition, and built-in structural validation.
Author: Cooper Wenhua <imgwho@gmail.com>
cwtwb is a Model Context Protocol (MCP) server and Python toolkit for generating Tableau Desktop workbook files (.twb / .twbx) from code or AI-driven tool calls.
It is designed as a workbook engineering layer, not as a conversational data exploration agent. The goal is to make workbook generation reproducible, inspectable, and safe to automate in local workflows, scripts, and CI.
The default workflow is:
Start from a known template (.twb or .twbx) or the built-in zero-config template
Add calculated fields and parameters
Build worksheets from stable chart primitives
Assemble dashboards and interactions
Save and validate a .twb or .twbx that opens in Tableau Desktop
For natural-language MCP authoring, cwtwb also supports a guided run workflow that starts from a real datasource file instead of a hand-written contract:
Start an authoring run from a local Excel or Hyper file
Inspect the datasource schema and pause for human confirmation
Build an analysis brief, present 2-4 candidate dashboard directions, and confirm the chosen direction
Draft, review, and finalize a structured authoring contract
Build and confirm a human-facing wireframe
Build a mechanical execution plan internally and generate the final workbook
Persist every intermediate artifact under tmp/agentic_run/{run_id}/
Interfaces
┌───────────────────────────────────────────────────────────────┐
│ ┌──────────────────────────┐ ┌───────────────────────────┐ │
│ │ MCP Server │ │ Python Library │ │
│ │ tools_workbook │ │ from cwtwb.twb_editor │ │
│ │ tools_layout │ │ import TWBEditor │ │
│ │ tools_migration │ │ │ │
│ │ tools_support │ │ editor.add_...() │ │
│ │ │ │ editor.configure_...() │ │
│ │ (Claude / Cursor / │ │ editor.save(...) │ │
│ │ VSCode / Claude Code) │ │ │ │
│ └─────────────┬────────────┘ └──────────────┬────────────┘ │
│ └──────────────┬────────────────┘ │
└───────────────────────────── ┼ ─────────────────────────────┘
▼
┌───────────────────────────────────────────────────────────────┐
│ TWBEditor │
│ ParametersMixin · ConnectionsMixin │
│ ChartsMixin · DashboardsMixin │
└──────────┬──────────────────┬──────────────────┬─────────────┘
▼ ▼ ▼
┌──────────────────┐ ┌──────────────┐ ┌──────────────────────┐
│ Chart Builders │ │ Dashboard │ │ Analysis & │
│ │ │ System │ │ Migration │
│ Basic DualAxis │ │ │ │ │
│ Pie Text │ │ layouts │ │ migration.py │
│ Map Recipes │ │ actions │ │ twb_analyzer.py │
│ │ │ dependencies│ │ capability_registry │
└────────┬─────────┘ └──────┬───────┘ └──────────┬───────────┘
└───────────────────┼──────────────────────┘
▼
┌───────────────────────────────────────────────────────────────┐
│ XML Engine (lxml) │
│ template.twb/.twbx → patch → validate → save │
└───────────────────────────────┬───────────────────────────────┘
▼
output.twb / output.twbxRelated MCP server: Tableau MCP
pip install cwtwbTo run the bundled Hyper-backed example that inspects .hyper files and
resolves the physical Orders_* table automatically, install the optional
example dependency as well:
pip install "cwtwb[examples]"To allow an MCP client to build Tableau workbooks automatically, add cwtwb
to that client's MCP configuration.
The launch command is the same across clients:
uvx cwtwbEach client stores this command in a different configuration format. Use the matching example below.
Open ~/Library/Application Support/Claude/claude_desktop_config.json on macOS or %APPDATA%\Claude\claude_desktop_config.json on Windows and add:
{
"mcpServers": {
"cwtwb": {
"command": "uvx",
"args": ["cwtwb"]
}
}
}Open Cursor Settings -> Features -> MCP
Click Add New MCP Server
Set Type to command
Set Name to cwtwb
Set Command to uvx cwtwb
claude mcp add cwtwb -- uvx cwtwbOpen the workspace .vscode/mcp.json file or your user-profile mcp.json
file and add:
{
"servers": {
"cwtwb": {
"command": "uvx",
"args": ["cwtwb"]
}
}
}In VSCode, you can open these files from the Command Palette with
MCP: Open Workspace Folder Configuration or
MCP: Open User Configuration. You can also use MCP: Add Server and
enter the same uvx cwtwb command through the guided flow.
For local testing without uvx, you can also start the server with:
python -m cwtwb.mcpUse TWBEditor(...) to start from a template and rebuild workbook content.
Use TWBEditor.open_existing(...) when you want to keep existing worksheets
and dashboards and reconfigure a sheet in place.
from cwtwb.twb_editor import TWBEditor
editor = TWBEditor("") # "" uses the built-in Superstore template
editor.clear_worksheets()
editor.add_calculated_field("Profit Ratio", "SUM([Profit])/SUM([Sales])")
editor.add_worksheet("Sales by Category")
editor.configure_chart(
worksheet_name="Sales by Category",
mark_type="Bar",
rows=["Category"],
columns=["SUM(Sales)"],
)
editor.add_worksheet("Segment Pie")
editor.configure_chart(
worksheet_name="Segment Pie",
mark_type="Pie",
color="Segment",
wedge_size="SUM(Sales)",
)
editor.add_dashboard(
dashboard_name="Overview",
worksheet_names=["Sales by Category", "Segment Pie"],
layout="horizontal",
)
editor.save("output/my_workbook.twb")Use worksheet clone/refactor when you want to duplicate an existing visual module and rebind only the cloned worksheet to a different core measure. This is especially useful for KPI cards such as turning a Sales KPI worksheet into an independent Profit KPI worksheet while preserving the original sheet.
from cwtwb.twb_editor import TWBEditor
editor = TWBEditor.open_existing("examples/worksheet_refactor_kpi_profit/5 KPI Design Ideas (2).twb")
editor.clone_worksheet("1. KPI", "1. KPI Profit")
editor.apply_worksheet_refactor("1. KPI Profit", {"Sales": "Profit"})
editor.set_worksheet_hidden("1. KPI Profit", hidden=False)
editor.save("output/kpi_profit_clone.twb")Available worksheet-refactor helpers:
clone_worksheet(source_worksheet, target_worksheet)
preview_worksheet_refactor(worksheet_name, replacements)
apply_worksheet_refactor(worksheet_name, replacements)
set_worksheet_hidden(worksheet_name, hidden=True)
apply_worksheet_refactor(...) now also performs a worksheet-local identity
normalization pass for generic Tableau Calculation_* fields. This stabilizes
pill labels after clone-and-replace workflows and returns post_process
evidence describing renamed calculation identities and worksheet-local rewrite
maps.
.twbx files are ZIP archives that bundle the workbook XML together with data extracts (.hyper) and image assets. cwtwb reads and writes them transparently:
from cwtwb.twb_editor import TWBEditor
# Open a packaged workbook — extracts and images are preserved automatically
editor = TWBEditor.open_existing("templates/dashboard/MyDashboard.twbx")
# Make changes as usual
editor.add_calculated_field("Profit Ratio", "SUM([Profit])/SUM([Sales])")
# Save as .twbx — re-bundles the updated .twb with the original extracts/images
editor.save("output/MyDashboard_v2.twbx")
# Or extract just the XML when the packaged format isn't needed
editor.save("output/MyDashboard_v2.twb")A plain .twb can also be packaged:
editor = TWBEditor("templates/twb/superstore.twb")
# ...
editor.save("output/superstore.twbx") # produces a single-entry ZIP with the .twb insideTool | Description |
| Create a guided datasource-first authoring run and persist its manifest under |
| List previously created authoring runs, their current status, and available artifacts |
| Inspect one authoring run, including confirmation gates, current artifact versions, and failure details |
| Re-open a previous authoring run after a client or server restart |
| Read the run datasource from the manifest and persist a structured schema summary for Excel or Hyper |
| Create the analysis brief scaffold from the current schema summary |
| Finalize 2-4 candidate directions plus the selected direction for the run |
| Create a contract draft from the schema summary plus a human brief |
| Review the current draft, apply profile-aware defaults, and produce clarification guidance |
| Merge review output with human answers and persist the finalized contract |
| Prefer MCP elicitation for schema, analysis, contract, and wireframe confirmation, with chat fallback when unsupported |
| Persist an approval or rejection for |
| Build a reviewable wireframe artifact from the confirmed contract |
| Finalize the wireframe review, including layout notes and supported actions |
| Reopen |
| Convert the finalized contract into a mechanical MCP tool-call plan |
| Execute the confirmed plan, save the workbook, and persist validation and analysis reports |
| Load a |
| Open an existing |
| List all available dimensions and measures |
| List worksheet names in the active workbook |
| List dashboards and the worksheet zones they reference |
| Add an interactive parameter for what-if analysis |
| Add a calculated field with Tableau formula |
| Remove a previously added calculated field |
| Clone an existing worksheet and its worksheet window |
| Preview worksheet-scoped field rewrites before mutating the workbook |
| Apply worksheet-scoped field rewrites while preserving the original worksheet |
| Add a new blank worksheet |
| Configure chart type and field mappings |
| Apply worksheet-level styling: background color, axis/grid/border visibility |
| Configure a dual-axis chart composition |
| Configure a showcase recipe chart such as |
| Create a dashboard combining worksheets |
| Add filter, highlight, URL, or go-to-sheet actions to a dashboard |
| Set or clear a worksheet caption using plain text |
| Hide or unhide a worksheet by updating its worksheet window metadata |
| Build an interactive structured dashboard flexbox layout |
| Show cwtwb's declared support boundary |
| Explain whether a chart or feature is core, advanced, recipe, or unsupported |
| Analyze a |
| Summarize the non-core gap of a template |
| Validate a workbook against the official Tableau TWB XSD schema (2026.1) |
| Run the built-in TWB migration workflow and pause for warning confirmation when needed |
| Configure the datasource to use a local Excel workbook and register fields from the selected sheet |
| Configure the datasource to use a local MySQL connection |
| Configure connection to an online Tableau Server |
| Configure the datasource to use a local Hyper extract connection |
| Save the workbook as |
The MCP server also exposes prompts that guide a datasource-first, human-in-the-loop workflow:
Prompt | Purpose |
| Top-level orchestration prompt for |
| Convert a human brief plus schema summary into a strict contract draft |
| Ask only the minimum missing business questions from a contract review |
| Turn a finalized contract into an execution-oriented internal MCP build plan |
| Guide a worksheet-scoped |
Use the guided run flow when you want a more structured Agentic BI authoring experience than a single free-form tool sequence.
High-level flow:
start_authoring_run(datasource_path=...)
intake_datasource_schema(run_id)
Human confirms the schema, preferably with interactive_stage_confirmation(..., stage="schema")
build_analysis_brief(...)
In agent_first mode, author and present 2-4 candidate directions, then finalize_analysis_brief(...)
Human confirms the selected direction, preferably with interactive_stage_confirmation(..., stage="analysis")
draft_authoring_contract(...)
review_authoring_contract_for_run(...)
finalize_authoring_contract(...)
Human confirms the contract, preferably with interactive_stage_confirmation(..., stage="contract")
build_wireframe(...)
finalize_wireframe(...)
Human confirms the wireframe, preferably with interactive_stage_confirmation(..., stage="wireframe")
build_execution_plan(...)
generate_workbook_from_run(...)
confirm_authoring_stage(...) is still the persistence step when a client falls
back to chat or when replaying an already-explicit human decision. By default,
execution_plan remains an internal artifact and is not a human approval gate.
Every run writes versioned artifacts, for example:
tmp/agentic_run/20260319-153045-a1b2c3d4/manifest.json
tmp/agentic_run/20260319-153045-a1b2c3d4/schema_summary.20260319-153046.json
tmp/agentic_run/20260319-153045-a1b2c3d4/contract_final.20260319-153120.json
tmp/agentic_run/20260319-153045-a1b2c3d4/execution_plan.20260319-153155.json
tmp/agentic_run/20260319-153045-a1b2c3d4/final_workbook.twb
tmp/agentic_run/20260319-153045-a1b2c3d4/validation_report.20260319-153205.json
tmp/agentic_run/20260319-153045-a1b2c3d4/analysis_report.20260319-153206.jsonSupported datasource types for this workflow today:
Excel (.xls, .xlsx, .xlsm)
Hyper (.hyper)
These are the stable building blocks the project should continue to promise:
Bar
Line
Area
Pie
Map
Text / KPI cards
Parameters and calculated fields
Basic dashboard composition
These are supported, but they are higher-level compositions or interaction features rather than the default surface area:
Scatterplot
Heatmap
Tree Map
Bubble Chart
Dual Axis — mark_color_1/2, color_map_1, reverse_axis_1, hide_zeroline, synchronized
Table Calculations — RANK_DENSE, RUNNING_SUM, WINDOW_SUM via add_calculated_field(table_calc="Rows")
KPI Difference badges — MIN(1) dummy axis + axis_fixed_range + color_map + customized_label
Donut (via extra_axes) — multi-pane Pie + white circle using configure_dual_axis(extra_axes=[...]); supports color_map for :Measure Names palette
Rich-text labels — configure_chart(label_runs=[...]) for multi-style KPI cards and dynamic titles with inline field values
Advanced worksheet styling — configure_worksheet_style supports pane-level cell/datalabel/mark styles, per-field label/cell/header formats, axis tick control, tooltip disabling, and all Tableau visual noise suppressions
Row dimension header suppression — configure_worksheet_style(hide_row_label="FieldName")
Filter zones, parameter controls, color legends
Dashboard filter, highlight, URL, and go-to-sheet actions
Worksheet captions
Declarative JSON layout workflows
Dashboard zone title control via show_title: false in layout dicts
These can be generated today, but they should be treated as recipes or examples rather than first-class promises:
Donut
Lollipop
Bullet
Bump
Butterfly
Calendar
Recipe charts are intentionally exposed through a single configure_chart_recipe
tool so the public MCP surface does not grow one tool at a time for every
showcase pattern.
This distinction matters because cwtwb is not trying to become a chart zoo or compete with Tableau's own conversational analysis tooling. The project is strongest when it provides a reliable, automatable workbook generation layer.
When you are not sure whether something belongs in the stable SDK surface:
Use list_capabilities to inspect the declared boundary
Use describe_capability to check a specific chart, encoding, or feature
Use analyze_twb or diff_template_gap before chasing a showcase template
This keeps new feature work aligned with the project's real product boundary instead of with whatever happens to appear in a sample workbook.
save() automatically validates the TWB XML structure before writing:
Fatal errors such as missing <workbook> or <datasources> raise TWBValidationError
Warnings such as missing <view> or <panes> are logged but do not block saving
Validation can be disabled with editor.save("output.twb", validate=False) or editor.save("output.twbx", validate=False)
TWBEditor.validate_schema() checks the workbook against the official Tableau TWB XSD schema (2026.1), vendored at vendor/tableau-document-schemas/:
result = editor.validate_schema()
print(result.to_text())
# PASS Workbook is valid against Tableau TWB XSD schema (2026.1)
# — or —
# FAIL Schema validation failed (2 error(s)):
# * Element 'workbook': Missing child element(s)...
result.valid # bool
result.errors # list[str] — lxml error messages
result.schema_available # False if the vendor submodule is not checked outThe same check is available as an MCP tool:
validate_workbook() # validate current open workbook in memory
validate_workbook(file_path="out.twb") # validate a file on disk (.twb or .twbx)XSD errors are informational — Tableau itself generates workbooks that occasionally deviate from the schema — but recurring errors signal structural problems worth fixing.
Layout | Description |
| Stack worksheets top to bottom |
| Place worksheets side by side |
| 2x2 grid layout for up to four worksheets |
| Declarative custom layouts for more complex dashboards |
Custom layouts can be built programmatically using a nested layout dictionary or via generate_layout_json for MCP workflows.
Use the canonical layout tree shape for nested dashboards:
{
"type": "container",
"direction": "horizontal",
"children": [
{"type": "worksheet", "name": "Sidebar", "fixed_size": 160},
{
"type": "container",
"direction": "vertical",
"children": [
{"type": "worksheet", "name": "Header", "fixed_size": 80},
{"type": "worksheet", "name": "Main Chart", "weight": 1}
]
}
]
}For compatibility with older MCP prompts and generated JSON files, add_dashboard
also accepts legacy container aliases and normalizes them recursively:
{"type": "horizontal", "children": [...]} and
{"type": "vertical", "children": [...]}. Unknown layout node types now raise a
clear error instead of silently creating an empty dashboard zone.
The examples/hyper_and_new_charts.py example uses the Sample - EU Superstore.hyper
extract bundled directly in the package (src/cwtwb/references/) and resolves the
physical Orders_* table via Tableau Hyper API before switching the workbook connection.
No repository clone is needed — install with pip install "cwtwb[examples]" and run directly.
cwtwb includes a migration subsystem for switching an existing .twb to a new
datasource — for example, repointing a workbook built on one Excel file to a
different Excel with a different schema, or migrating between language variants
of the same dataset.
Migration is a multi-step workflow. Each step is available as both an MCP tool and a Python function:
1. inspect_target_schema → Scan the target Excel and list its columns
2. profile_twb_for_migration → Inventory which fields the workbook uses
3. propose_field_mapping → Match source fields to target columns (fuzzy)
4. preview_twb_migration → Dry-run: show what would change, blockers/warnings
5. apply_twb_migration → Write the migrated .twb + JSON reportsmigrate_twb_guided is a convenience wrapper that runs steps 2–5 in sequence
and pauses automatically when only low-confidence field matches remain, returning
a warning_review_bundle for human review before proceeding.
from cwtwb.migration import migrate_twb_guided_json
import json
# One-call guided migration
result = migrate_twb_guided_json(
file_path="templates/SalesDashboard.twb",
target_source="data/new_data_source.xlsx",
output_path="output/SalesDashboard_migrated.twb",
)
bundle = json.loads(result)
if bundle["status"] == "warning_review_required":
# Inspect low-confidence matches and confirm or override them
print(bundle["warning_review_bundle"])
# Re-run with confirmed mappings
result = migrate_twb_guided_json(
file_path="templates/SalesDashboard.twb",
target_source="data/new_data_source.xlsx",
output_path="output/SalesDashboard_migrated.twb",
mapping_overrides={"Old Field Name": "New Column Name"},
)When using cwtwb as an MCP server, an AI agent can run the full workflow:
inspect_target_schema(target_source="data/new_data_source.xlsx")
→ returns column list and data types
migrate_twb_guided(
file_path="templates/SalesDashboard.twb",
target_source="data/new_data_source.xlsx",
output_path="output/SalesDashboard_migrated.twb"
)
→ returns status: "applied" or "warning_review_required"A completed migration writes three files:
File | Contents |
| Migrated workbook with rewritten field references |
| Per-field status: mapped / warning / blocked |
| Final source→target field mapping for audit |
scope="workbook" migrates all worksheets. Pass a worksheet name to limit
migration to a single sheet.
examples/migrate_workflow/ contains a template .twb, the original
Superstore Excel, a target Chinese-locale Superstore Excel, and a runnable
script:
python examples/migrate_workflow/test_migration_workflow.pycwtwb/
|-- src/cwtwb/
| |-- __init__.py
| |-- capability_registry.py
| |-- config.py
| |-- contracts/
| |-- authoring_contract.py
| |-- authoring_run.py
| |-- charts/
| |-- connections.py
| |-- dashboard_actions.py
| |-- dashboard_dependencies.py
| |-- dashboard_layouts.py
| |-- dashboards.py
| |-- field_registry.py
| |-- layout.py
| |-- layout_model.py
| |-- layout_rendering.py
| |-- mcp/
| |-- parameters.py
| |-- skills/
| |-- twb_analyzer.py
| |-- twb_editor.py
| |-- validator.py
| `-- server.py
|-- tests/
|-- examples/
|-- docs/
|-- pyproject.toml
`-- README.md# Install in editable mode
pip install -e .
# Run test suite
pytest --basetemp=output/pytest_tmp
# Run the mixed showcase example
python examples/scripts/demo_all_supported_charts.py
# Run the advanced Hyper-backed example
python examples/scripts/demo_hyper_and_new_charts.py
# Run the guided migration example
python examples/migrate_workflow/test_migration_workflow.py
# Start MCP server
cwtwbAGPL-3.0-or-later
Add a calculated field to the datasource.
| Name | Required | Description | Default |
|---|---|---|---|
| field_name | Yes | ||
| formula | Yes | ||
| datatype | No | real | |
| role | No | ||
| field_type | No | ||
| default_format | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description bears full responsibility for disclosing behavioral traits. The description lacks details about whether the operation is reversible, what side effects occur (e.g., updating the datasource), any authorization requirements, or the response format. Although there is an output schema, the description does not indicate the nature of the output.
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 (e.g., bullet points or sections) that could improve readability for a multi-parameter tool. It is front-loaded with the key action and resource.
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 (6 parameters, 2 required, no schema descriptions, no annotations), the description is incomplete. It does not explain the return value (though output schema exists), the behavior of the tool, or how parameters interact. The agent would have limited understanding of how to use it correctly.
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 6 parameters with 0% description coverage, meaning the schema provides no descriptions for the parameters. The tool description does not elaborate on any parameters, such as what 'role', 'field_type', or 'default_format' mean. The agent would have to infer meaning from parameter 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 clearly states the action ('Add') and the resource ('calculated field') and specifies it is added to a 'datasource'. However, it does not differentiate from sibling tools like 'add_parameter' or 'add_worksheet' which also add entities, but the resource is distinct enough for an AI agent to infer 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?
No guidance is provided on when to use this tool versus alternatives such as 'add_parameter' or 'add_dashboard'. There is no mention of prerequisites, such as needing an existing datasource, 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 dashboard combining multiple worksheets.
| Name | Required | Description | Default |
|---|---|---|---|
| dashboard_name | Yes | ||
| worksheet_names | Yes | ||
| width | No | ||
| height | No | ||
| layout | No | vertical |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must convey behavior. It states the tool creates a dashboard, which implies a write operation. However, it does not disclose what happens to existing dashboards with the same name, whether the operation is reversible, or if it requires specific permissions. The description is minimal but not misleading.
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 of 6 words, which is concise and front-loaded with the main action. However, it is arguably too brief for a tool with 5 parameters and no other documentation, sacrificing clarity for brevity.
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 (which may document return values), the description can focus on behavior. However, with no annotations and 5 parameters, the description should provide more context about parameter roles and usage. It is adequate for a simple tool but incomplete for the complexity of combining worksheets with layout options.
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%, meaning the description does not explain any parameters beyond their names. The description mentions 'multiple worksheets' but does not clarify that 'worksheet_names' is a list of worksheet names, nor does it explain 'layout' options (e.g., 'vertical' vs 'horizontal'). The 'width' and 'height' parameters have defaults but no semantic context. With 5 parameters and 0% coverage, the description adds insufficient meaning.
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 'Create a dashboard combining multiple worksheets' clearly states the verb 'create' and resource 'dashboard', and the purpose of combining worksheets. It distinguishes from siblings like 'add_dashboard_action' and 'add_worksheet' by focusing on dashboard creation, but does not explicitly differentiate from 'add_calculated_field' or 'add_parameter' which have different purposes.
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., worksheets must already exist) or when not to use it. Siblings like 'add_dashboard_action' suggest adding actions to an existing dashboard, implying this tool is for initial creation, but this is not stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Add an interaction action to a dashboard.
| Name | Required | Description | Default |
|---|---|---|---|
| dashboard_name | Yes | ||
| action_type | Yes | ||
| source_sheet | Yes | ||
| target_sheet | No | ||
| fields | No | ||
| event_type | No | on-select | |
| caption | No | ||
| url | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
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 does not mention side effects, permissions needed, or return value behavior. The description is minimal, leaving the agent uninformed about what happens when the action is added.
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 short sentence, which is concise. However, it is too sparse and does not provide enough information for the tool's complexity.
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 (8 parameters, no annotations, low schema coverage), the description is insufficient. It does not explain return values, action types, or how this tool fits into the dashboard authoring workflow.
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 should clarify parameter semantics. The description lists no parameters and provides no additional meaning beyond the schema. The schema has 8 parameters with defaults and types, but the description adds nothing.
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 says 'Add an interaction action to a dashboard', which identifies the verb and resource. However, it does not differentiate from sibling tools like 'add_dashboard', 'add_parameter', or 'add_worksheet', which also add items to dashboards or workbooks.
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 other add tools. The description does not mention prerequisites, context, 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.
Add a parameter to the workbook.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | ||
| datatype | No | real | |
| default_value | No | 0 | |
| domain_type | No | range | |
| min_value | No | ||
| max_value | No | ||
| granularity | No | ||
| allowed_values | No | ||
| default_format | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
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 does not mention side effects, permissions needed, or any constraints (e.g., parameter uniqueness). 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?
Single sentence, concise and front-loaded. No wasted words, but could benefit from additional context 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 complexity (9 params, no output schema info in description), the description is incomplete. It does not explain what 'add' means (insert? replace?), or the impact on existing parameters. An output schema exists but 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 coverage is 0% meaning the description provides no parameter info. However, with 9 parameters, the baseline is low. The description adds no semantic meaning beyond the schema, which already has names and defaults. Score 3 because schema has defaults and 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 'Add a parameter to the workbook' clearly states the action (add) and resource (parameter to the workbook). It distinguishes itself from siblings like add_calculated_field and add_dashboard by specifying a different 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?
No guidance on when to use this tool versus alternatives (e.g., when to add a parameter vs. a calculated field). No prerequisites or context provided about workbook requirements.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Add a new blank worksheet to the workbook.
| Name | Required | Description | Default |
|---|---|---|---|
| worksheet_name | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must fully disclose behavior. It states that a blank worksheet is added, but does not mention side effects (e.g., whether the worksheet becomes active, how it interacts with existing worksheets, or if it requires save). No annotation 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 single, clear sentence with no wasted words. It is appropriately concise for a simple 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?
Given the tool has one parameter and an output schema (likely returns the worksheet ID or success), the description is minimal. It does not describe the return value or any constraints. For a simple add operation, this is adequate but not complete; the agent may need more context to use it correctly.
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 required parameter ('worksheet_name') with 0% description coverage. The description does not explain what 'worksheet_name' means or any constraints (e.g., uniqueness, length). Since there is only one parameter, the baseline is 4, but the description adds no value beyond the schema, so a 3 is appropriate.
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') and the resource ('a new blank worksheet to the workbook'). It distinguishes from sibling tools like 'clone_worksheet' or 'configure_chart', though it could be more specific about the context (e.g., that it adds to an existing workbook).
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 'clone_worksheet' or 'add_dashboard'. It does not specify prerequisites (e.g., workbook must be open) or exclusions. The context signals show no annotations, so the description carries the full burden.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Analyze a TWB file against cwtwb's declared capabilities.
| Name | Required | Description | Default |
|---|---|---|---|
| file_path | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden for behavioral disclosure. It does not mention whether the analysis is read-only, destructive, or requires authentication. The term 'analyze' suggests a read operation, but this is not explicit.
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 short sentence that gets to the point. However, it could be more concise by removing jargon like 'cwtwb's declared capabilities' which may require external context.
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 only one parameter, a simple purpose, and an output schema (not shown), the description is minimally complete. However, it lacks details about the analysis result or when to use this tool vs siblings like 'profile_twb_for_migration', making it less complete 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 description coverage is 0%, so the description must compensate for the single parameter 'file_path'. It does not elaborate on the format, valid values, or constraints of file_path. However, with only one parameter and its name being self-explanatory, the baseline is 3.
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 'Analyze a TWB file against cwtwb's declared capabilities' uses a specific verb ('Analyze') and resource ('TWB file'), but the phrase 'cwtwb's declared capabilities' is unclear without context. The tool's purpose is distinguishable from siblings like 'profile_twb_for_migration' or 'validate_workbook', but the description lacks specificity about what 'analyze' entails compared to other analysis tools.
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. Given the large number of sibling tools, such as 'profile_twb_for_migration' or 'validate_workbook', the description should clarify scenarios where analysis against 'declared capabilities' is appropriate, but it does not.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Apply a workbook migration and write a migrated TWB plus reports.
| Name | Required | Description | Default |
|---|---|---|---|
| file_path | Yes | ||
| target_source | Yes | ||
| output_path | Yes | ||
| scope | No | workbook | |
| mapping_overrides | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It indicates the tool is likely destructive (applying migrations, writing files) and does not mention idempotency or side effects. The description adds some behavioral context ('write a migrated TWB plus reports') but lacks details on error handling or state changes.
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 that states the core action. It is front-loaded and contains no filler, but could benefit from slightly more structure (e.g., listing key parameters).
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 5 parameters (3 required) and no annotation support, the description is incomplete. It does not explain return values despite having an output schema, nor does it cover migration scope or overrides. Sibling tools with similar purposes demand clearer differentiation.
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 mentions 'file_path', 'target_source', 'output_path', and 'scope' implicitly via 'workbook migration', but provides no details on 'mapping_overrides'. The description does not explain parameter meaning or expected formats beyond what the schema minimally indicates.
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 'Apply a workbook migration and write a migrated TWB plus reports', which is a clear verb+resource combination. However, it does not differentiate from the sibling 'migrate_twb_guided' or 'preview_twb_migration', leaving ambiguity about when to use this tool versus those.
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 'migrate_twb_guided' or 'preview_twb_migration'. No context about prerequisites, typical workflow, or exclusions is given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Rewrite one worksheet to use replacement fields without touching others.
| Name | Required | Description | Default |
|---|---|---|---|
| worksheet_name | Yes | ||
| replacements | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description must disclose behavior. It states 'rewrite ... using replacement fields' but doesn't mention mutability, whether operation is reversible, or if it requires prior preview. For a mutation tool with no annotations, more detail is needed.
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, no fluff. It front-loads the action and scope. Could add a second sentence for when to use or behavior, but current is acceptable.
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 (refactoring a worksheet), and no annotations or output schema description, the description is incomplete. It omits what 'replacements' are, whether it validates, and how errors are handled. Output schema exists but description doesn't leverage it.
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% (no descriptions), but description mentions 'replacement fields', hinting at the 'replacements' parameter. However, it doesn't clarify the format or meaning of the replacement fields, leaving ambiguity. With 0 parameters described in schema, baseline is 3 but could be higher.
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 action ('rewrite one worksheet'), resource ('worksheet'), and scope ('without touching others'). It distinguishes from siblings like 'preview_worksheet_refactor' or 'configure_worksheet_style', though not explicitly.
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?
Implies use when needing to refactor a single worksheet without affecting others, but lacks explicit when-to-use vs alternatives, such as when to use 'apply_twb_migration' or 'preview_worksheet_refactor' first.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Build analysis_brief.json and .md. In agent_first mode this is a scaffold the agent must fill explicitly.
| Name | Required | Description | Default |
|---|---|---|---|
| run_id | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so the description carries the full burden. It indicates the tool builds files and is a scaffold in agent_first mode, implying it requires agent action, but does not disclose side effects, permissions, or error 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 two concise sentences, each adding distinct information. 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?
Given the tool's simplicity (one parameter, no nested objects) and the presence of an output schema, the description is somewhat adequate but could better explain the relationship with sibling tools and the 'run_id' parameter.
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 required parameter 'run_id' with 0% schema description coverage. The description adds no information about what 'run_id' is or how to obtain it, leaving the agent without guidance.
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 builds 'analysis_brief.json and .md', specifying the output files. However, it lacks differentiation from the sibling 'finalize_analysis_brief', which likely completes the brief.
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 mentions 'In agent_first mode this is a scaffold the agent must fill explicitly', providing context about its use in a specific mode, but gives no guidance on when to use this tool vs alternatives like 'finalize_analysis_brief'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Build a mechanical execution_plan.json from the current final contract.
| Name | Required | Description | Default |
|---|---|---|---|
| run_id | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It does not disclose behavioral traits such as whether it is destructive, requires specific stages to be complete, or any side effects beyond building the file.
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, concise and front-loaded. However, it could be slightly more informative 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 that an output schema exists, the description need not explain return values. However, the tool is part of a complex authoring workflow with many sibling tools; the description lacks context about how this step fits into the overall process.
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 mentions 'current final contract' but does not explain the role of the 'run_id' parameter, which is required. The parameter semantics are not clarified beyond what the schema provides.
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 'Build' and the specific resource 'mechanical execution_plan.json' derived from 'current final contract'. It distinguishes the tool's purpose from siblings, though it could specify the context of use more precisely.
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 guidance on when to use this tool versus alternatives. Sibling tools include similar 'build_' and 'finalize_' actions, but the description does not clarify prerequisites or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Build wireframe.json and .md, including an ASCII dashboard sketch.
| Name | Required | Description | Default |
|---|---|---|---|
| run_id | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses the output types (JSON, markdown) and mentions an ASCII sketch, but does not explain side effects, file creation behavior, or whether it overwrites existing files. The description adds value beyond the schema (which only has a run_id), so it's not insufficient, but could be more detailed.
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 that conveys key information. It is front-loaded with the primary output (files) and a notable feature (ASCII sketch). No unnecessary 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?
Given the tool has one simple parameter and an output schema (not shown), the description covers the main output artifacts and a distinctive feature. It is complete enough for an agent to understand the tool's purpose and output format, though more detail on parameter usage would improve it.
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. The description does not mention the 'run_id' parameter or its role. However, the schema itself is simple (one string parameter), and the description implies that the tool operates on a specific run via the context. A baseline 3 is appropriate given the schema's simplicity, but the description adds no parameter details.
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 builds 'wireframe.json and .md, including an ASCII dashboard sketch.' This clearly identifies the action (build) and the output artifacts (JSON and markdown files) with a specific feature (ASCII sketch). It distinguishes from sibling tools like 'generate_layout_json' or 'finalize_wireframe' by mentioning the sketch, though not explicitly contrasting.
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 lacks guidance on when to use this tool vs alternatives. For instance, it doesn't clarify when to use 'build_wireframe' versus 'generate_layout_json' or 'finalize_wireframe'. No context about prerequisites, required prior steps, or exclusions is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Clone an existing worksheet and its worksheet window.
| Name | Required | Description | Default |
|---|---|---|---|
| source_worksheet | Yes | ||
| target_worksheet | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the full burden. It does not disclose any behavioral traits such as side effects (e.g., whether cloning copies dependencies like calculated fields), authorization requirements, or impact on source worksheet. The description only states what the tool does, not how it behaves.
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 directly states the purpose. It could be considered under-specified, but it is concise and front-loaded with the key action. However, it sacrifices necessary detail for brevity.
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 (cloning involves copying multiple elements), the description is incomplete. It does not mention what exactly is cloned (e.g., fields, formatting, filters). Although an output schema exists, the description lacks behavioral context needed 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%, meaning the schema provides no descriptions. The tool description does not add any meaning to the parameters 'source_worksheet' and 'target_worksheet'. It is unclear what format or identifiers are expected (e.g., worksheet names or IDs).
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 'Clone an existing worksheet and its worksheet window', which clearly indicates the action (clone) and the resource (worksheet and its window). It distinguishes from siblings like 'add_worksheet' and 'configure_worksheet_style', though it doesn't explicitly differentiate from 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. For example, it doesn't mention when to use 'clone_worksheet' instead of 'add_worksheet' or 'configure_worksheet_style'. There is no context on prerequisites or limitations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Configure chart type and field mappings for a worksheet.
| Name | Required | Description | Default |
|---|---|---|---|
| worksheet_name | Yes | ||
| mark_type | No | Automatic | |
| columns | No | ||
| rows | No | ||
| color | No | ||
| size | No | ||
| label | No | ||
| detail | No | ||
| wedge_size | No | ||
| sort_descending | No | ||
| tooltip | No | ||
| filters | No | ||
| geographic_field | No | ||
| measure_values | No | ||
| map_fields | No | ||
| mark_sizing_off | No | ||
| axis_fixed_range | No | ||
| customized_label | No | ||
| color_map | No | ||
| text_format | No | ||
| map_layers | No | ||
| label_runs | No | ||
| label_param | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
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 does not mention that this tool modifies an existing worksheet (mutation), nor does it discuss side effects, authorization needs, or error conditions. The description is too vague for a tool with 23 parameters.
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 underspecified for a complex tool with many parameters. It could be improved by adding brief parameter grouping or key behaviors without becoming overly long.
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 high complexity (23 parameters, no schema description coverage), the description is inadequate. It does not explain how chart types are set, what field mappings are expected, or how the output is structured. The existence of an output schema does not relieve the description of providing high-level 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%, meaning the description adds no meaning to any of the 23 parameters. The description merely says 'chart type and field mappings' but does not explain how parameters like 'color', 'filters', or 'axis_fixed_range' map to chart configuration. The description should at least summarize parameter 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 verb 'configure' and the resource 'chart type and field mappings for a worksheet', which distinguishes it from sibling tools like 'configure_dual_axis' or 'configure_worksheet_style'. It specifies what is being configured.
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 'configure_chart_recipe' or 'configure_dual_axis'. It does not mention prerequisites (e.g., the worksheet must already exist) 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.
Configure a showcase recipe chart through the shared recipe registry.
| Name | Required | Description | Default |
|---|---|---|---|
| worksheet_name | Yes | ||
| recipe_name | Yes | ||
| recipe_args | No | ||
| auto_ensure_prerequisites | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
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 mentions 'shared recipe registry', implying the chart is configured from a predefined recipe, but does not disclose side effects, permissions, or what happens when auto_ensure_prerequisites is false. It is not contradictory but lacks behavioral detail.
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 conveys the core purpose without extra words. It is front-loaded and 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?
Given the tool has 4 parameters (2 required), an output schema, and no annotations, the description is insufficient. It does not explain what 'configure' entails, the role of recipe_args, or the return value. The output schema exists but the description doesn't leverage it to reduce completeness burden.
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 should add meaning. However, it does not describe any parameters. The schema already defines fields like worksheet_name, recipe_name, recipe_args, and auto_ensure_prerequisites, but the description adds no extra semantics beyond the tool's purpose. Baseline 3 applies given the schema is the only source.
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 the tool configures a showcase recipe chart via the shared recipe registry, providing a clear verb ('configure') and resource ('showcase recipe chart'). It distinguishes itself from sibling tools like 'configure_chart' and 'configure_dual_axis' by specifying 'through the shared recipe registry', but lacks explicit differentiation from similar recipe-related tools.
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 vs alternatives. Given the sibling tools include 'configure_chart' and many others, the description should clarify use cases or when not to use it. The context of 'showcase recipe' is implied but not explicitly compared.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Configure a dual-axis chart composition.
| Name | Required | Description | Default |
|---|---|---|---|
| worksheet_name | Yes | ||
| mark_type_1 | No | Bar | |
| mark_type_2 | No | Line | |
| columns | No | ||
| rows | No | ||
| dual_axis_shelf | No | rows | |
| color_1 | No | ||
| size_1 | No | ||
| label_1 | No | ||
| detail_1 | No | ||
| color_2 | No | ||
| size_2 | No | ||
| label_2 | No | ||
| detail_2 | No | ||
| synchronized | No | ||
| sort_descending | No | ||
| filters | No | ||
| wedge_size_1 | No | ||
| wedge_size_2 | No | ||
| show_labels | No | ||
| hide_axes | No | ||
| hide_zeroline | No | ||
| mark_sizing_off | No | ||
| size_value_1 | No | ||
| size_value_2 | No | ||
| mark_color_2 | No | ||
| mark_color_1 | No | ||
| reverse_axis_1 | No | ||
| color_map_1 | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must fully disclose behavioral traits. It fails to mention that this tool modifies an existing worksheet, whether it is destructive, requires specific permissions, or how it interacts with other configurations. The description is too brief.
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 only one sentence long, which is concise, but it sacrifices clarity and completeness. It does not front-load key information or explain what 'configure' means. The sentence is too vague to be considered effective.
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 high complexity (29 parameters) and no annotations or parameter descriptions, the description is severely inadequate. It does not explain the tool's effect, return value (output schema exists but not referenced), or how to use it 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-level information beyond the schema titles. With 29 parameters, the description must compensate, but it does not explain any of them. The baseline of 1 is appropriate, but 2 because the schema titles provide some minimal meaning.
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 'Configure a dual-axis chart composition' which gives a general sense of the tool's purpose. However, it lacks specificity about what 'configure' entails and does not differentiate from sibling tools like 'configure_chart' or 'configure_worksheet_style'.
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 'configure_chart' or 'configure_worksheet_style'. There is no mention of prerequisites, context, or conditions for appropriate use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Apply worksheet-level styling: background color, axis/grid/border visibility.
| Name | Required | Description | Default |
|---|---|---|---|
| worksheet_name | Yes | ||
| background_color | No | ||
| hide_axes | No | ||
| hide_gridlines | No | ||
| hide_zeroline | No | ||
| hide_borders | No | ||
| hide_band_color | No | ||
| hide_col_field_labels | No | ||
| hide_row_field_labels | No | ||
| hide_droplines | No | ||
| hide_reflines | No | ||
| hide_table_dividers | No | ||
| disable_tooltip | No | ||
| pane_cell_style | No | ||
| pane_datalabel_style | No | ||
| pane_mark_style | No | ||
| pane_trendline_hidden | No | ||
| label_formats | No | ||
| cell_formats | No | ||
| header_formats | No | ||
| axis_style | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so the description carries the full burden. It clearly states that it applies styling, which implies a mutation (not read-only). However, it does not disclose what happens to previous styling, whether changes are reversible, or if it triggers any side effects like re-rendering. The description is adequate but lacks depth.
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, concise, and front-loaded with the main purpose. However, it could be more precise by listing all categories (e.g., 'pane styles, label formats').
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 (21 parameters, 0% schema coverage, no annotations, no output schema explained), the description is too brief. It does not explain return values, the scope of styling, or how to use complex parameters like pane_cell_style or label_formats. A more detailed description is needed for effective tool 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?
Schema description coverage is 0%, so the description must compensate. It only lists three categories (background color, axis/grid/border visibility) but there are 21 parameters covering many more aspects (e.g., hide_band_color, pane_cell_style, label_formats). The description misses most 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 a specific verb 'apply' and a clear resource 'worksheet-level styling', listing the exact styling aspects (background color, axis/grid/border visibility). This distinguishes it from sibling tools like configure_chart, which deals with chart-level styling, and clone_worksheet, which duplicates a worksheet.
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 configure_chart or set_worksheet_caption. It does not mention prerequisites (e.g., the worksheet must exist) or provide any context on 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.
Approve or reject one gated authoring stage.
| Name | Required | Description | Default |
|---|---|---|---|
| run_id | Yes | ||
| stage | Yes | ||
| approved | Yes | ||
| notes | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description bears full responsibility for disclosing behavioral traits. The description does not mention what happens upon approval or rejection (e.g., workflow progression, immutability of decision), whether the action is reversible, or any side effects on the authoring run. It merely states the function without behavioral context.
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, short sentence that conveys the core action efficiently. It is front-loaded with the verb and object. However, it could be slightly expanded to include key context without losing conciseness.
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 moderate complexity (4 parameters, 3 required) and lack of annotations, the description is incomplete. It does not explain the gating mechanism, the role of the stage parameter, or the workflow context. The output schema exists but is not described. Sibling tools suggest a broader authoring workflow, but this tool's description fails to situate it within that workflow.
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 description adds no information about parameters beyond the input schema. The schema itself provides titles and types but no descriptions. The description does not explain the meaning of 'run_id', 'stage', 'approved', or 'notes', leaving the agent to infer from names. With 0% coverage, the description should 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 ('approve or reject') and the resource ('one gated authoring stage'). It distinguishes the tool from siblings like 'reopen_authoring_stage' and 'interactive_stage_confirmation', but could be more specific about what a 'gated authoring stage' is.
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 'interactive_stage_confirmation' or 'reopen_authoring_stage'. It does not mention prerequisites, such as the need for a run_id from an ongoing authoring run, nor does it specify when approval versus rejection is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new workbook from a TWB or TWBX template file.
| Name | Required | Description | Default |
|---|---|---|---|
| template_path | No | ||
| workbook_name | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
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 does not state whether the tool modifies existing files, requires specific permissions, or if the creation is reversible. The word 'create' implies a write operation, but no further details are given.
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, short sentence that directly states the tool's purpose. It is concise and front-loaded, though it could benefit from additional context.
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 and the relatively simple operation (creation from template), the description provides the core purpose. However, it lacks details on parameter behavior, error conditions, or what happens to existing workbooks. It is adequate but not comprehensive.
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 2 parameters with 0% description coverage, meaning the description adds no detail beyond the schema. However, the parameter names ('template_path', 'workbook_name') are fairly self-explanatory. The description clarifies that the template is from a TWB/TWBX file, which adds 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 specifies the action ('create a new workbook') and the source material ('from a TWB or TWBX template file'). However, it does not differentiate from siblings like 'generate_workbook_from_run' or 'save_workbook', which could create 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?
The description lacks any guidance on when to use this tool versus alternatives (e.g., 'generate_workbook_from_run' or 'open_workbook'). It does not mention prerequisites, such as whether the template file must exist or be provided via a path.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Describe one declared capability and its support tier.
| Name | Required | Description | Default |
|---|---|---|---|
| kind | Yes | ||
| name | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the full burden. It accurately states the tool's behavior (describing one capability) but does not disclose side effects, permissions, or error conditions. The description is honest but 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?
The description is a single, efficient sentence with no wasted words. It is front-loaded with the key action and resource.
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 is low (simple retrieval with 2 parameters and an output schema), the description is mostly adequate. However, the lack of parameter semantics and usage guidance reduces completeness for an agent without external knowledge.
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 does not explain what 'kind' and 'name' refer to or how to obtain valid values. The description adds no meaning beyond the schema field titles, leaving the agent to guess.
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 retrieves a capability and its support tier, using a specific verb ('describe') and resource ('capability'). It distinguishes from sibling tools like 'list_capabilities' by focusing on a single capability, though it does not explicitly contrast 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 (e.g., 'list_capabilities'). The description lacks context on prerequisites or appropriate usage scenarios, leaving the agent to infer from the name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Summarize the non-core capability gap of a TWB template.
| Name | Required | Description | Default |
|---|---|---|---|
| file_path | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
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 does not mention if the tool is read-only, has side effects, requires authentication, or any constraints. The description only states the purpose but not the 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 a single sentence, front-loaded with the action, and contains no unnecessary words. It is appropriately concise for a simple 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?
Given the tool's complexity (one parameter, no annotations, but an output schema exists), the description is too sparse. It does not explain the tool's purpose relative to siblings, the format of the summary, or prerequisites. The output schema may provide return structure, but the description should still set expectations.
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 input schema provides no description for the 'file_path' parameter. The description does not explain what 'file_path' should point to (e.g., a TWB file, a specific format). With only one parameter, the description should add context 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 states 'Summarize the non-core capability gap of a TWB template', which is a specific verb ('Summarize') and resource ('non-core capability gap of a TWB template'). It is clear and distinct from sibling tools like 'profile_twb_for_migration' or 'analyze_twb'.
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 'profile_twb_for_migration' or 'analyze_twb'. The description does not explain what constitutes a 'non-core capability gap' or in what context this is relevant.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a contract draft scaffold from the current schema summary plus a human brief.
| Name | Required | Description | Default |
|---|---|---|---|
| run_id | Yes | ||
| human_brief | Yes | ||
| rewrite | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It states the tool creates a 'draft scaffold', implying a non-destructive, preliminary action. However, it does not disclose if this is reversible, any side effects, or if it modifies existing state. The description is adequate but lacks depth.
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 that front-loads the action and inputs. No unnecessary words. It earns its place.
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 3 parameters, no annotations, and an output schema exists (though not detailed here), the description is moderately complete. It explains the core action and inputs but omits details about the output or how 'rewrite' affects behavior. With 0% schema coverage, more parameter context would improve 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?
Schema coverage is 0%, so the description must compensate. It mentions 'human_brief' as an input, but 'run_id' and 'rewrite' are not explained. The description adds minimal meaning beyond the parameter names. Baseline for 0% coverage is low, but the description does partially clarify 'human_brief'.
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 'Create' and the resource 'contract draft scaffold', specifying the inputs 'current schema summary plus a human brief'. However, it does not distinguish from siblings like 'finalize_authoring_contract' or 'review_authoring_contract', which could cause confusion about when to use this vs. other contract-related tools.
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. There is no mention of prerequisites, such as needing a schema summary or human brief ready, nor any exclusion criteria. The description is too vague for an agent to determine appropriate context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Finalize analysis_brief from chat overrides or an edited Markdown review file.
| Name | Required | Description | Default |
|---|---|---|---|
| run_id | Yes | ||
| user_answers_json | No | ||
| markdown_path | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must disclose behavioral traits. However, it only states the input sources without explaining what 'finalize' entails (e.g., whether it overwrites existing data, triggers side effects, or requires a specific run 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, short sentence that conveys the core purpose without unnecessary words. It is front-loaded 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 (3 parameters, output schema exists), the description is somewhat complete but lacks details on parameter usage and the finalization process. The output schema may compensate, but the description itself does not clarify what the tool returns.
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%, but the description adds some context by naming the two optional parameters ('user_answers_json' and 'markdown_path') as sources for the finalization. However, it does not explain the required 'run_id' or the semantics of each 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 a specific verb-resource combination ('finalize analysis_brief') and mentions two distinct input sources ('chat overrides' or 'edited Markdown review file'). This clearly indicates the tool's purpose and distinguishes it from sibling tools like 'build_analysis_brief'.
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 does not specify when to use this tool versus other sibling tools (e.g., 'build_analysis_brief', 'confirm_authoring_stage'). It provides no context about prerequisites or conditions under which the tool should be invoked.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Merge contract review defaults with human answers and persist contract_final.json.
| Name | Required | Description | Default |
|---|---|---|---|
| run_id | Yes | ||
| user_answers_json | No | ||
| markdown_path | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must fully disclose behavior. It mentions merging defaults with answers and persisting a file, but does not clarify if the operation is destructive (overwrites existing contract), requires specific permissions, or if it returns a status or the final contract. The output schema exists but is not 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 that is concise and front-loaded with the main action. However, it could be slightly more informative without adding length.
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 does not need to detail return values. However, with no annotations and 0% schema coverage, the description should provide more context about the merging logic and side effects. It is minimally adequate but has 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%, so the description must compensate. It only mentions 'human answers' and 'defaults', but does not explain parameters 'run_id', 'user_answers_json', or 'markdown_path' in detail. The description adds some context but leaves ambiguity.
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 ('merge', 'persist') and the specific resource ('contract_final.json'). It distinguishes from siblings like 'draft_authoring_contract' and 'review_authoring_contract' by indicating it is a finalization step.
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. The description implies it is used after human answers are provided, but does not mention prerequisites or when not to use it. Sibling names suggest related stages, but no differentiation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Finalize wireframe review notes or normalized actions before planning.
| Name | Required | Description | Default |
|---|---|---|---|
| run_id | Yes | ||
| user_answers_json | No | ||
| markdown_path | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must fully disclose behavioral traits. However, the description only states a high-level purpose and does not mention effects such as whether the tool modifies data, requires authentication, or has side effects. It does not disclose what happens to the wireframe or notes after finalization. This is insufficient for an agent to understand the tool's 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 extremely short (one clause), which could be seen as concise, but it sacrifices clarity and completeness. It does not earn its place because it fails to convey sufficient information. A score of 3 reflects adequate brevity but with significant gaps.
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 3 parameters (one required) and no output schema description in the input, the description is incomplete. It does not explain the return value or how the parameters relate to the finalization process. The agent cannot reliably use this tool based solely on the provided description.
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%, meaning the description must explain parameter semantics. However, the description does not describe any of the three parameters (run_id, user_answers_json, markdown_path) or their roles. Without this, the agent cannot understand what values to provide or how they affect the tool's operation.
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 says 'Finalize wireframe review notes or normalized actions before planning.' This gives a general sense of the tool's purpose: it finalizes something related to wireframe review. However, it does not clearly specify the verb-resource relationship; 'finalize' is vague and does not distinguish from siblings like 'build_wireframe' or 'build_analysis_brief'. It lacks specificity about what exactly is being finalized and how it differs from other finalization tools.
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. It mentions 'before planning' but does not explain what conditions warrant its use, nor does it reference any sibling tools. Without any when/when-not guidance or mentions of alternatives, the agent has little context for appropriate invocation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Generate and save a dashboard layout JSON file.
| Name | Required | Description | Default |
|---|---|---|---|
| output_path | Yes | ||
| layout_tree | Yes | ||
| ascii_preview | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden for behavioral disclosure. It only states 'Generate and save,' which implies file creation but does not mention side effects (e.g., overwrites existing file, requires specific permissions, or what happens on error). No behavioral traits beyond the basic action are 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 a single sentence, concise and to the point. However, it is too brief, missing essential details. Conciseness is good but at the expense of 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 complexity (3 required params, nested objects, no annotations, output schema present), the description is inadequate. It does not explain what the JSON represents, how the layout_tree should be structured, or what the output contains. The output schema exists but is not referenced in the description.
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 does not describe any parameters (output_path, layout_tree, ascii_preview). The schema itself has titles but no descriptions. The tool name suggests layout generation, but parameter semantics are entirely absent 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 states 'Generate and save a dashboard layout JSON file.' This clearly identifies the verb (generate/save) and resource (dashboard layout JSON file). However, it does not differentiate from sibling tools like 'build_wireframe' or 'configure_chart', which might also involve layout generation. The purpose is clear but lacks sibling 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. Given many sibling tools (e.g., build_wireframe, configure_chart), explicit usage context is missing. There is no mention of prerequisites, workflow position, 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.
Execute the confirmed execution plan, save the workbook, and persist reports.
| Name | Required | Description | Default |
|---|---|---|---|
| run_id | Yes | ||
| output_twb_path | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
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 mentions saving and persisting but does not state if the operation is destructive, requires authentication, or has side effects (e.g., overwriting existing files).
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 (7 words) and front-loaded. However, it sacrifices clarity for brevity. For 2 parameters, it could be slightly more verbose without losing conciseness.
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 (workflow tool with siblings) and lack of annotations, the description is insufficient. It does not explain output schema, return values, or the relationship to other tools like 'build_execution_plan'.
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%, meaning the description must explain parameters. It does not mention what 'run_id' or 'output_twb_path' are or how they relate to the tool's purpose. The description adds 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 states it executes a plan and saves a workbook, but the verb 'execute' is vague and doesn't specify the exact action (e.g., 'generate' or 'build'). The term 'confirmed execution plan' hints at a previous step, but the purpose is somewhat 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 siblings like 'resume_authoring_run' or 'save_workbook'. The description does not mention prerequisites or that 'run_id' must come from a prior plan execution.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Report whether the connected MCP client supports form elicitation.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
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 describes a read-only check, which is implicit. No additional behavioral traits (e.g., idempotency, side effects) are disclosed, but the tool is simple and no annotations exist to contradict.
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 with no wasted words. Perfectly concise for a tool with no parameters.
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 no parameters and existence of an output schema, the description is sufficient for a simple boolean check. However, it lacks context on what 'form elicitation' means and when to use this over similar capability 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 100% with no parameters. The description adds no parameter info, but baseline is 4 for zero-param tools since schema provides full coverage.
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 it reports whether the MCP client supports form elicitation. It uses a specific verb ('report') and resource ('client interaction capabilities'), but does not differentiate from sibling tools like 'describe_capability' or 'list_capabilities'.
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 'list_capabilities' or 'describe_capability'. The description implies usage when checking form support, but no exclusions or context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return the manifest-backed status for one authoring run.
| Name | Required | Description | Default |
|---|---|---|---|
| run_id | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
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 states 'manifest-backed status' but does not clarify whether this is a read-only operation, what side effects exist, or if authentication is required. The description is too terse to disclose behavioral traits beyond the basic purpose.
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. It is front-loaded with the action and resource. However, it is so brief that it sacrifices clarity for conciseness.
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 a single required parameter and an output schema, the description should at least hint at the output structure or how the status is represented. It does not, leaving the agent with insufficient context to use the tool 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%, meaning the description does not explain the meaning of 'run_id' beyond its schema title. The description fails to add any context about what the run_id represents or how to obtain it.
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 specifies the action ('return') and the resource ('manifest-backed status for one authoring run'), providing a clear verb+resource pair. However, it does not differentiate from sibling tools like 'list_authoring_runs' or 'review_authoring_contract_for_run', which may also relate to run status.
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 does not provide guidance on when to use this tool versus alternatives such as 'list_authoring_runs' (which might return statuses for multiple runs) or 'review_authoring_contract_for_run'. No context for prerequisites or postconditions is given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Inspect the first-sheet schema of a target Excel datasource.
| Name | Required | Description | Default |
|---|---|---|---|
| target_source | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries burden. It discloses it inspects only the first sheet of Excel, but does not mention any side effects or permissions. With no annotations, this is adequate but 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, 10 words, no filler. Front-loaded with verb and resource. Every word earns its place.
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 only 1 parameter, no annotations, but with an output schema (which presumably explains return value), the description is nearly complete. Could add that it returns field names and types, but output schema likely covers that.
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%, yet description adds no meaning to the 'target_source' parameter. The description only mentions 'target Excel datasource' but does not explain what 'target_source' is or how to specify it.
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 states verb 'inspect' and resource 'first-sheet schema of a target Excel datasource'. It clearly distinguishes from siblings like 'intake_datasource_schema' by specifying Excel and first-sheet 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 when-to-use or when-not-to-use guidance. However, from context it's implied to inspect schema before using other datasource tools. No alternatives mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Inspect the datasource declared in the run manifest and persist schema_summary.
| Name | Required | Description | Default |
|---|---|---|---|
| run_id | Yes | ||
| preferred_sheet | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
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 states that it persists schema_summary but does not clarify what that entails (e.g., whether it modifies state, requires specific permissions, or has side effects). The verb 'persist' suggests mutation, but no confirmation or details are given.
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 efficiently communicates the core action. It is front-loaded with the key verb and resource, but could be slightly more structured without adding length.
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 an output schema and is part of a complex authoring workflow, the description is incomplete. It does not explain what 'schema_summary' contains, how it relates to the run, or what happens if the datasource is missing. Sibling tools like 'inspect_target_schema' and 'describe_capability' provide similar functionality, but no distinction is made.
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 should compensate. The description mentions 'datasource declared in the run manifest', which implies 'run_id' is the run identifier, but 'preferred_sheet' is not explained. With 0% coverage and only 2 parameters, the description adds minimal semantics beyond the schema field 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 uses specific verbs ('Inspect', 'persist') and clearly identifies the resource ('datasource declared in the run manifest') and outcome ('persist schema_summary'). It distinguishes itself from sibling tools like 'inspect_target_schema' by focusing on the datasource from the run manifest rather than a target schema.
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 'inspect_target_schema' or 'describe_capability'. There is no mention of prerequisites (e.g., must have an active run) or scenarios where this tool should be avoided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Prefer MCP elicitation for stage confirmation, with chat fallback when unsupported.
| Name | Required | Description | Default |
|---|---|---|---|
| run_id | Yes | ||
| stage | Yes | ||
| stage_summary | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the full burden. It only hints at fallback behavior without detailing what the tool does (e.g., prompts user, returns confirmation), side effects, 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 very short (one sentence), but its brevity sacrifices clarity. It could be expanded to be more useful 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 (3 params, output schema present), the description is insufficient. It does not explain what the tool returns, how it interacts with the user, or how it relates to sibling tools like confirm_authoring_stage.
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 does not explain any of the three parameters (run_id, stage, stage_summary). It adds no meaning beyond the schema's basic type and required status.
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 'Prefer MCP elicitation for stage confirmation, with chat fallback when unsupported' uses jargon (MCP elicitation) and does not clearly state what the tool does. It vaguely indicates confirmation of a stage but lacks a clear verb and resource.
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 mentions preferring MCP elicitation with chat fallback, which implies a usage context but does not explicitly state when to use this tool versus alternatives like confirm_authoring_stage or reopen_authoring_stage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all known authoring runs and their current status.
| Name | Required | Description | Default |
|---|---|---|---|
| output_dir | No | tmp/agentic_run |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must fully disclose behavior. It correctly indicates a read operation ('list') and implies no side effects. However, it does not mention any potential filtering, pagination, or authorization requirements. The description is adequate but lacks depth.
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 that directly conveys the purpose. No extraneous 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?
Given the tool's simplicity (one optional parameter, list operation), the description is reasonably complete. The presence of an output schema may compensate for not describing the return format. However, among many sibling tools related to authoring runs, more context on what distinguishes this from other run-related tools would be beneficial.
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 optional parameter ('output_dir') with a default. The description does not mention this parameter, but since schema description coverage is 0%, the description should compensate. However, the parameter is self-explanatory (output directory), and the default suggests it's not critical. The description's lack of parameter info is offset by the parameter's simplicity, so score is above baseline.
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 all known authoring runs and their current status. It uses a specific verb ('list') and resource ('authoring runs'), and the context of 'current status' adds useful detail. However, it does not differentiate from sibling tools like 'get_run_status' or 'resume_authoring_run', which might overlap in 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 is provided on when to use this tool versus alternatives such as 'get_run_status' (which might return a single run's status). There is no mention of 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 cwtwb's declared capability boundary.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
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 indicates a read-only operation (listing), which is appropriate for a capability introspection tool. However, it does not disclose any potential side effects or behavior beyond listing, which is acceptable for a simple query.
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 concise (4 words) and front-loaded. It is efficiently structured with no unnecessary words, but it could be slightly expanded to improve completeness without losing conciseness.
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 zero parameters and a presumably simple output (the schema exists but isn't detailed here), the description is adequate. However, it lacks context on what 'capability boundary' means or how the output is structured, which may leave an AI agent unsure of the return format.
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 the input schema is empty. The description adds no further meaning beyond the schema, but since there are no parameters, a baseline of 4 might be considered, but given the brevity and lack of context, 3 is appropriate.
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 the capability boundary of 'cwtwb', which is a specific verb-resource combination. It distinguishes itself from sibling tools like 'describe_capability' and 'get_client_interaction_capabilities' by focusing on the declared boundary rather than a single capability or client-specific capabilities.
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 'describe_capability' or 'get_client_interaction_capabilities'. No context on prerequisites or typical scenarios is given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List dashboards and their worksheet zones in the current workbook.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden. It describes the tool as listing dashboards and zones, implying a read-only operation, which is reasonable but lacks details on side effects or access requirements.
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, clear sentence with no extraneous information. It is appropriately 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?
The tool is simple with zero parameters and an output schema exists (not shown). The description is sufficient given the simplicity, though it could mention that it operates on the currently open workbook.
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 100% with zero parameters, so the description does not need to add parameter info. It correctly states the scope (current workbook) which adds context beyond the empty 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 tool lists dashboards and their worksheet zones in the current workbook, with a specific verb and resource. However, it does not differentiate from siblings like 'add_dashboard' or 'list_worksheets'.
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., 'add_dashboard' or 'list_worksheets'). The context of 'current workbook' is implied but not explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all available fields in the current workbook datasource.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries the burden. It states the tool 'lists' fields, implying a read-only operation with no side effects. However, it does not clarify behavior like caching, pagination, or what 'available' means exactly (e.g., include hidden fields?). The description is minimally adequate but lacks depth.
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 with the key action. Every word earns its place. No wasted text.
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 no parameters, presence of output schema, and low complexity, the description is nearly complete. It identifies the resource and scope. It could optionally mention that the output includes field names and types, but the output schema presumably covers that. Slight lack of detail on what 'available' means, but adequate for a zero-parameter 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?
The input schema has zero parameters, so the description does not need to add parameter details. The description correctly implies no configuration is needed. With 100% schema coverage (trivially), a baseline of 3 applies, but the description adds value by specifying the source ('current workbook datasource').
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 all available fields in the current workbook datasource. It specifies the resource ('fields') and scope ('current workbook datasource'). While it distinguishes from sibling tools like 'add_calculated_field' and 'remove_calculated_field', it does not explicitly differentiate from potential field-related tools.
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 before other actions that require knowledge of available fields (e.g., adding calculated fields). However, it does not explicitly state when to use this tool versus alternatives, nor does it mention any prerequisites or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List worksheet names in the current workbook.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description states it lists 'names', which is a non-destructive read operation. Since no annotations are provided, the description carries the full burden. It clearly indicates no side effects, though it doesn't mention what happens if the workbook is empty or if there are many worksheets.
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 of 5 words, perfectly concise and front-loaded. Every word is necessary and earns its place.
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 simplicity (no parameters, no output schema needed since output is presumably list of strings), the description is complete. It tells the agent exactly what to expect.
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 no parameters, so there is nothing to explain. The description adds no parameter semantics, but this is acceptable since there are none. Baseline 3 applies.
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 it lists worksheet names in the current workbook, using a specific verb ('list') and resource ('worksheet names'). It is distinct from siblings like list_dashboards, list_fields, and add_worksheet, which have different purposes.
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 to know worksheet names, and it is clearly a read-only operation. However, it does not explicitly state when not to use it or compare to alternatives like list_fields or list_dashboards, which might be relevant if the agent needs other information.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Run the built-in migration workflow and pause for warning confirmation when needed.
| Name | Required | Description | Default |
|---|---|---|---|
| file_path | Yes | ||
| target_source | Yes | ||
| output_path | No | ||
| scope | No | workbook | |
| mapping_overrides | No | ||
| apply_if_no_blockers | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses a key behavioral trait: it pauses for warning confirmation. This is beyond what annotations provide (none). However, it does not mention side effects, required permissions, or what happens after confirmation. The output schema is present but not referenced.
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, 13 words) and front-loaded with the primary action. It is concise, though it could benefit from a bit 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?
Given the tool has 6 parameters (2 required) and an output schema, the description lacks necessary context for an agent to use it correctly. It does not explain the migration workflow, what warnings trigger pauses, or how to handle confirmation. Sibling tools like 'apply_twb_migration' and 'preview_twb_migration' suggest alternatives, but no comparison is made.
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 additional meaning for any of the 6 parameters. The description does not explain 'mapping_overrides', 'scope', 'apply_if_no_blockers', or 'output_path'. The schema alone 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 clearly states the tool runs a built-in migration workflow and pauses for warning confirmation. It uses specific verbs ('Run', 'pause') and identifies the resource ('migration workflow'). However, it does not differentiate from siblings like 'apply_twb_migration' or 'preview_twb_migration', which may overlap.
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 'apply_twb_migration' or 'preview_twb_migration'. There is no mention of prerequisites or when not to use it. The description implies usage for guided migration, but lacks explicit context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Open an existing workbook (.twb or .twbx) for in-place worksheet editing.
| Name | Required | Description | Default |
|---|---|---|---|
| file_path | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden. It states 'in-place worksheet editing', which implies the tool modifies the workbook directly. However, it does not disclose whether it requires specific permissions, locks the file, or how it handles unsaved changes. The behavioral transparency is adequate but not thorough.
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 clearly states the purpose. Every word is necessary, with no filler or redundancy.
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 (not shown but present) and a single parameter, the description is minimally adequate. However, it lacks context about what happens after opening (e.g., if the workbook is loaded into memory, if subsequent tools operate on it) and does not mention prerequisites like file existence or format validity.
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%, but there is only one parameter (file_path). The description adds no additional meaning beyond the parameter name; it does not specify path format, allowed file extensions (though implied), or whether absolute/relative paths are accepted. With low coverage, the description should compensate but 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 verb 'Open' and the resource 'existing workbook', specifying file types (.twb or .twbx) and the purpose 'for in-place worksheet editing'. It distinguishes this from sibling tools like 'create_workbook' or 'save_workbook' by focusing on opening an existing file.
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 to edit worksheets in an existing workbook, but it does not explicitly state when not to use it or provide alternatives. Among many sibling tools, it doesn't clarify that for creating new workbooks one should use 'create_workbook' or for saving use 'save_workbook'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Preview a workbook migration onto a target datasource.
| Name | Required | Description | Default |
|---|---|---|---|
| file_path | Yes | ||
| target_source | Yes | ||
| scope | No | workbook | |
| mapping_overrides | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the full burden. It does not disclose whether the tool is read-only or destructive, what side effects occur (if any), or if it modifies any state. The term 'preview' suggests no mutation, but this is not explicit.
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 is too terse and lacks necessary detail, making it underspecified rather than efficiently packed.
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, 0% schema coverage, no annotations, but has an output schema), the description is incomplete. It does not explain what the preview returns (despite output schema existing), nor does it provide context about when to use this tool in the migration workflow.
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, but it does not explain any parameter. The description mentions 'migration' and 'target datasource' vaguely, but does not elaborate on 'file_path', 'target_source', 'scope', or 'mapping_overrides'. The purpose of 'scope' with default 'workbook' and 'mapping_overrides' is not explained.
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 the tool 'Previews a workbook migration onto a target datasource.' The verb 'preview' and resource 'workbook migration' are clear, but the description is vague about what 'preview' entails (e.g., does it show potential issues, a diff, or a success/failure indicator?). It does not distinguish this from siblings like 'apply_twb_migration' or 'profile_twb_for_migration'.
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 vs. alternatives like 'apply_twb_migration' or 'migrate_twb_guided'. There is no mention of prerequisites (e.g., need to profile first) or conditions under which preview is useful.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Preview worksheet-scoped field rewrites without mutating the workbook.
| Name | Required | Description | Default |
|---|---|---|---|
| worksheet_name | Yes | ||
| replacements | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations are absent, so the description must convey behavior. It clearly states 'without mutating the workbook' (read-only preview). However, it does not disclose return value structure, whether changes are simulated, or any side effects. The output schema exists but is not described; without it, the agent may not know what the preview returns.
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 concisely captures purpose and key constraint. No wasted words; front-loaded with action and scope.
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 output schema exists, the description need not detail return values. However, the tool has nested objects and 0% schema coverage, so the description should explain the replacements map. It partially compensates with 'worksheet-scoped field rewrites' but lacks detail on what constitutes a rewrite. Completeness is adequate but not thorough.
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 does not describe the parameters 'worksheet_name' or 'replacements' beyond their names. The description mentions 'worksheet-scoped' hinting at worksheet_name, but does not explain that 'replacements' is a map from old field names to new names. The agent has no semantic guidance beyond the schema 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 states 'Preview worksheet-scoped field rewrites without mutating the workbook,' which clearly specifies the action (preview), scope (worksheet-scoped field rewrites), and key trait (non-mutating). It distinguishes from sibling tools like 'apply_worksheet_refactor' (which applies changes) and 'preview_twb_migration' (which is workbook-level). However, the term 'field rewrites' could be more explicit about what is being replaced.
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 use when wanting to see the effect of field replacements before committing, contrasting with 'apply_worksheet_refactor'. No explicit when-not-to-use or alternative guidance is provided. The sibling list includes 'preview_twb_migration' and 'apply_worksheet_refactor', but the description does not directly compare.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Profile workbook datasources and worksheet scope before migration.
| Name | Required | Description | Default |
|---|---|---|---|
| file_path | Yes | ||
| scope | No | workbook | |
| target_source | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
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 states the tool profiles datasources and worksheet scope, implying it is a read-only analysis tool. However, it does not disclose side effects, authentication needs, or whether it modifies the workbook. The term 'profile' suggests no destructive action, but this is implicit.
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 concise (one sentence) and front-loaded with the verb and resource. It is appropriately sized, but could benefit from a brief mention of parameters or output 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 (3 parameters, output schema exists, and multiple sibling tools), the description is minimally adequate. It covers the core purpose but lacks detail on parameters and usage context. The presence of an output schema somewhat mitigates the need to describe return values.
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%, meaning no parameter descriptions exist in the schema. The description does not explain what 'file_path', 'scope', or 'target_source' mean or how they affect behavior. The parameter names are self-explanatory to some extent, but the description fails to add semantic value beyond their 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 'Profile workbook datasources and worksheet scope before migration' clearly identifies the tool's purpose with a specific verb ('profile') and resource ('workbook datasources and worksheet scope'). It distinguishes from sibling tools like 'analyze_twb' and 'migrate_twb_guided' by focusing on pre-migration profiling.
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 'analyze_twb' or 'preview_twb_migration'. It does not mention prerequisites or conditions that would trigger its use, leaving the agent to infer from the tool name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Scan source and target schema and propose a field mapping.
| Name | Required | Description | Default |
|---|---|---|---|
| file_path | Yes | ||
| target_source | Yes | ||
| scope | No | workbook | |
| mapping_overrides | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden but only says 'Scan source and target schema.' It does not disclose if this is a read-only operation, whether it modifies state, what permissions are needed, or how long it might take. The output schema exists but the description doesn't hint at what it returns.
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 of 8 words, which is very concise. However, it is too minimal; it sacrifices clarity and completeness for brevity. Still, it avoids unnecessary 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?
Given that there is an output schema, the description does not need to explain return values, but it still lacks context on tool behavior, prerequisites, and how to use parameters. The tool has 4 parameters with 0% schema description coverage, so more detail in the description is warranted.
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 description adds no parameter details. The description does not explain the meaning of 'file_path,' 'target_source,' 'scope,' or 'mapping_overrides.' The schema provides some hints (e.g., 'scope' defaults to 'workbook'), but the description fails to clarify how these parameters affect the mapping proposal.
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 'Scan' and the resource 'source and target schema' to 'propose a field mapping.' It distinguishes itself from siblings like 'inspect_target_schema' and 'migrate_twb_guided' by focusing on proposing a mapping rather than just inspecting or executing migration.
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 'inspect_target_schema' or 'migrate_twb_guided.' There is no mention of prerequisites (e.g., schema must be available), nor any exclusion criteria (e.g., when not to use).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Remove a previously added calculated field.
| Name | Required | Description | Default |
|---|---|---|---|
| field_name | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
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 states the removal action, which implies a destructive operation (deletion). However, it does not clarify whether the field is permanently deleted or can be recovered, nor does it mention any prerequisites (e.g., field must exist). The description is adequate but 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?
The description is a single, concise sentence that front-loads the action. Every word is necessary and there is no extraneous text.
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 one parameter, no annotations, and an output schema exists. Given the simplicity, the description is reasonably complete but could mention that the field must exist and that the operation may affect formulas depending on it. The output schema likely covers return values, so that is not a gap.
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 required parameter 'field_name' with 0% schema description coverage. The description adds meaning by specifying it's a 'previously added calculated field', clarifying that the field must exist. This provides context beyond the parameter name 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?
The description uses the verb 'Remove' and the resource 'calculated field', clearly stating the action and object. It distinguishes from sibling tools like 'add_calculated_field' by implying the inverse operation. However, it could be more specific about the scope (e.g., from the active worksheet or workbook).
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 removing a calculated field that was previously added. It does not provide explicit when-to-use or when-not-to-use guidance, nor does it reference alternatives. The sibling 'add_calculated_field' is the obvious counterpart, but no explicit comparison is made.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Reopen analysis, contract, wireframe, or execution_plan after confirmation or generation failure.
| Name | Required | Description | Default |
|---|---|---|---|
| run_id | Yes | ||
| stage | Yes | ||
| notes | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
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 indicates the tool modifies state (reopens), but does not describe side effects, permissions needed, or idempotency. Without annotations, more detail would be beneficial.
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 essential information, front-loading the key action. No superfluous 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?
Given zero schema coverage, no annotations, and an output schema, the description is too minimal. It should clarify parameter semantics (e.g., valid stage values) and behavior (e.g., is reopening idempotent? what is 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%, so the description must add meaning to parameters. It does not describe 'run_id', 'stage', or 'notes' beyond their schema titles. 'stage' is ambiguous (what are valid stages?), and 'notes' purpose is 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 uses a specific verb 'Reopen' with clear targets ('analysis, contract, wireframe, or execution_plan') and a condition ('after confirmation or generation failure'), which distinguishes it from siblings like 'confirm_authoring_stage' and 'build_execution_plan'.
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 this tool should be used after a confirmation or generation failure, but does not explicitly state when not to use it or mention alternatives. Sibling tools like 'confirm_authoring_stage' and 'finalize_*' provide context but are not referenced.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Resume a previous authoring run by id.
| Name | Required | Description | Default |
|---|---|---|---|
| run_id | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden. The description says 'resume' which implies the run was paused/suspended, but it doesn't specify side effects, state requirements, or error conditions. It is adequate but not detailed.
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, front-loaded with the verb. It is concise and contains no 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?
The tool has only one parameter and an output schema (not shown). Given low complexity, the description is minimally adequate but lacks context about return value, state transitions, or error handling.
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% (no descriptions in schema). The description does not explain the 'run_id' parameter beyond its title. With only one parameter, a brief hint would help but the title is self-explanatory.
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 'Resume a previous authoring run by id.' It uses a specific verb ('Resume') and resource ('authoring run'), and the sibling tools include 'start_authoring_run' and 'list_authoring_runs', which are clearly related. However, it does not explicitly differentiate from 'reopen_authoring_stage' or 'confirm_authoring_stage'.
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 vs. alternatives like 'start_authoring_run' or 'reopen_authoring_stage'. It does not mention prerequisites (e.g., run must exist, must be in a resumable state).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Review a draft authoring contract and apply profile-aware defaults.
| Name | Required | Description | Default |
|---|---|---|---|
| contract_json | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must fully disclose behavior. It states 'apply profile-aware defaults' but does not explain what 'profile-aware' means, what defaults are applied, or any side effects. It does not mention if the contract is modified, if approval is needed, or if the action is reversible. Significant behavioral details are missing.
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, 7 words) and front-loaded with the core action. It earns its place but is arguably too concise, omitting critical details. However, for a simple tool with one parameter, brevity is appropriate, and no unnecessary words are present.
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 one required parameter with no schema description and no annotations, the description is inadequate. It fails to explain how 'contract_json' should be provided, what 'profile-aware defaults' means, or what the output schema contains. For a complex workflow involving authoring contracts, the description leaves major 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?
The input schema has one required parameter, 'contract_json', with no description coverage (0%). The tool description provides no additional meaning about this parameter beyond its name, such as format (JSON string), expected structure, or constraints. The agent has no information on how to construct the parameter value.
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 'Review a draft authoring contract and apply profile-aware defaults' uses specific verbs ('review' and 'apply') and identifies the resource ('draft authoring contract'). However, it does not distinguish from sibling tools like 'review_authoring_contract_for_run', which suggests a similar purpose but likely differs in scope. The purpose is clear but lacks differentiation.
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 'review_authoring_contract_for_run' or 'finalize_authoring_contract'. There is no mention of prerequisites, context (e.g., after 'draft_authoring_contract'), or when not to use it. The agent is left 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.
Review the current contract draft and persist contract_review.json.
| Name | Required | Description | Default |
|---|---|---|---|
| run_id | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description must disclose behavioral traits. It says it persists a file but doesn't clarify if it modifies anything else, requires authorization, or has side effects. The output schema exists but isn't 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?
Very short and direct, but lacks necessary detail. Could benefit from a brief expansion to cover key aspects without being 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 description doesn't mention what the output contains. Given the existence of many sibling tools for authoring, the description should clarify the role of this tool in the workflow.
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 doesn't explain the 'run_id' parameter's purpose or constraints. The description only mentions the action, not the parameter meaning.
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 reviews a contract draft and persists a JSON file, but it doesn't specify what 'contract_review.json' contains or how it relates to the authoring run. The purpose is somewhat clear but lacks detail to distinguish it from 'review_authoring_contract' sibling.
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 vs. 'review_authoring_contract' or other sibling tools like 'confirm_authoring_stage'. The description implies it's for reviewing a contract, but no context on prerequisites or order of operations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Save the workbook as a TWB file. Use a .twbx extension to produce a packaged workbook (ZIP) that bundles the XML with any data extracts and images carried over from the source .twbx.
| Name | Required | Description | Default |
|---|---|---|---|
| output_path | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so the description must carry the behavioral burden. It clearly states the side effect (saving to file), the packaging behavior for .twbx, and what gets bundled (XML, extracts, images). This is comprehensive for a save 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?
Two sentences, zero wasted words. Front-loaded with the core action, followed by the extension-specific behavior.
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 parameter and no annotations. The description covers the essential behavior and packaging nuance. It doesn't mention error conditions or permissions, but those are not critical for a save tool with an 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. It explains that output_path should include extension to trigger packaging, adding meaning beyond the schema's title 'Output Path'. Only one parameter, and the description adds key nuance.
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 'Save' and the resource 'workbook as a TWB file', and distinguishes between .twb and .twbx extensions, which differentiates it from sibling tools like open_workbook or create_workbook.
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 it (to save) and mentions the .twbx extension for packaging, but does not explicitly state when not to use it or provide alternatives among siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Configure the workbook datasource to use a local Excel connection.
| Name | Required | Description | Default |
|---|---|---|---|
| filepath | Yes | ||
| sheet_name | No | ||
| fields | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
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 does not explain whether the connection replaces an existing one, what happens to existing data, or any side effects. It also doesn't mention permission requirements or file accessibility. The output schema exists but isn't referenced 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 of 9 words, efficient and front-loaded. It uses active voice and clear terminology. However, it could be slightly improved by adding a brief note about parameters or behavior without significant bloat.
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, 0% schema coverage, no annotations, and a task that likely involves file I/O and connection configuration, the description is incomplete. It lacks information about return values (output schema exists but not described), error conditions, and parameter details. The output schema existence suggests richer behavior, but the description doesn't leverage it.
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 'local Excel connection' but doesn't describe individual parameters like filepath, sheet_name, or fields. The schema provides names, but the description adds no additional meaning, missing an opportunity to clarify the purpose of sheet_name (e.g., which sheet to use) or fields (e.g., column mapping).
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 configures a workbook datasource to use a local Excel connection, specifying the action (configure), resource (workbook datasource), and target type (local Excel connection). It distinguishes itself from sibling tools like set_hyper_connection or set_mysql_connection, which target different datasource types.
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., set_hyper_connection for Hyper files). It doesn't mention prerequisites like whether a workbook must already be open or if the Excel file must exist. Sibling tools suggest different datasource types, but the description provides no comparative context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Configure the workbook datasource to use a local Hyper extract connection.
| Name | Required | Description | Default |
|---|---|---|---|
| filepath | Yes | ||
| table_name | No | Extract | |
| tables | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It states the tool configures a connection but does not disclose if it modifies the workbook in-place, requires a specific state, or has side effects (e.g., closing existing connections). No mention of permissions or response 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?
Single sentence, no wasted words. Front-loads the main purpose. Perfectly concise for a simple 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?
Given 3 parameters (1 required), no annotations, and an output schema (but description doesn't reference it), the description is incomplete. It doesn't explain what the output schema represents or how the parameters interact. Sibling tools suggest a data source context, but more detail is needed for effective 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?
Schema description coverage is 0%, so description must compensate. It does not describe any parameter semantics (filepath, table_name, tables) beyond their schema titles. Baseline 3 is appropriate since no param info is added, but coverage is low.
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 configures a workbook datasource to use a local Hyper extract connection. The verb 'Configure' and resource 'workbook datasource' are specific, and it distinguishes from sibling tools like set_excel_connection or set_mysql_connection by specifying 'Hyper extract'.
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 (e.g., set_excel_connection, set_mysql_connection). It does not mention prerequisites or when not to use it. The context of using a local Hyper extract is implied but not elaborated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Configure the workbook datasource to use a local MySQL connection.
| Name | Required | Description | Default |
|---|---|---|---|
| server | Yes | ||
| dbname | Yes | ||
| username | Yes | ||
| table_name | Yes | ||
| port | No | 3306 |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so description must fully disclose behavior. It does not state whether the tool modifies the workbook immediately, requires an open workbook, or what happens on failure. No mention of side effects or required permissions.
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, no wasted words. But lacks structure; could benefit from a note about required vs optional parameters or order of operations.
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 (4 required), no output schema info (though output schema exists, its content is not described), and no annotations, the description is too sparse to ensure correct invocation. Missing details like whether the connection is persistent or temporary.
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%, meaning no descriptions for parameters. The description adds no parameter-level semantics; it just names the tool. Parameters like 'server', 'dbname' are self-explanatory but 'table_name' could be confused with a table to create or select. No hint about how 'port' default is used.
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 configures a workbook datasource for a local MySQL connection, which is clear. However, 'local' may be confusing as parameters include a 'server' field. It distinguishes from sibling connection tools (set_excel_connection, etc.) but not explicitly.
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 vs other connection tools (set_excel_connection, set_hyper_connection, etc.). No prerequisites or alternative suggestions provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Configure the workbook datasource to use a Tableau Server connection.
| Name | Required | Description | Default |
|---|---|---|---|
| server | Yes | ||
| dbname | Yes | ||
| username | Yes | ||
| table_name | Yes | ||
| directory | No | /dataserver | |
| port | No | 82 |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the full burden. It indicates that this tool modifies the workbook datasource (a write operation), but does not disclose side effects, such as whether existing connections are overwritten or if the workbook must be open. It does not mention authentication requirements, error conditions, or whether the change is reversible. A score of 3 is fair as it conveys the basic action but lacks depth.
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, front-loading the key action. It contains no fluff. However, it could be slightly longer to include important details about when to use it or parameter hints 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 (6 params, no annotations, no output schema description), the description is incomplete. It does not explain return values (output schema exists but not described), prerequisites, or post-conditions. However, the tool's purpose is relatively straightforward, and the output schema may provide structure. A score of 3 reflects that it meets minimum viability but lacks 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?
Schema description coverage is 0%, so the description does not explain any parameter semantics. The tool has 6 parameters (4 required), and the description adds no meaning beyond the schema. However, the parameter names (server, dbname, username, table_name, directory, port) are somewhat self-explanatory. Baseline is 3 due to low coverage, and the description fails to compensate, but the names help slightly.
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's purpose: to configure a workbook datasource to use a Tableau Server connection. It specifies the verb 'configure' and the resource 'workbook datasource with Tableau Server connection'. However, it does not explicitly distinguish it from sibling tools like set_hyper_connection or set_mysql_connection, which are similar but for different connection types.
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 set_excel_connection, set_hyper_connection, or set_mysql_connection. The description does not mention prerequisites, context, or when it is appropriate to switch connections. The agent is left to infer usage from the connection type.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Set or clear a plain-text worksheet caption.
| Name | Required | Description | Default |
|---|---|---|---|
| worksheet_name | Yes | ||
| caption | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so description must carry behavioral information. It states the tool sets or clears a caption, implying a mutation. However, it does not disclose if the operation is reversible, if it requires permissions, or what the output schema indicates (return value).
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 that efficiently communicates the core functionality with no unnecessary 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?
Given the tool has 2 required parameters and no nested objects, the description is reasonably complete. However, it lacks details about return value (output schema exists but description doesn't mention it) and edge cases like clearing caption behavior.
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. It explains that the caption is 'plain-text' and that the tool can 'clear' (likely by empty string). This adds value beyond the schema, which only lists names and types. However, it does not detail what 'clear' means in terms of input.
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 sets or clears a plain-text worksheet caption, using the verb 'set' and specifying the resource (worksheet caption). It distinguishes from siblings like 'set_worksheet_hidden' by focusing on caption content.
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. For instance, there is no mention that to clear a caption one can pass an empty string, nor when to use this over other worksheet modification tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Initialize a new guided authoring run from an Excel or Hyper datasource.
| Name | Required | Description | Default |
|---|---|---|---|
| datasource_path | Yes | ||
| output_dir | No | tmp/agentic_run | |
| resume_if_exists | No | ||
| authoring_mode | No | agent_first | |
| force_new | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden. It only states initialization but does not disclose what happens if a run already exists, whether it overwrites, or any side effects. The 'resume_if_exists' and 'force_new' parameters imply behavior, but the description does not clarify 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?
The description is a single sentence, concise and front-loaded with the action. However, it could be slightly more informative without adding length, so not a 5.
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 (5 parameters, no annotations, no output schema description) and the presence of closely related sibling tools, the description is incomplete. It lacks guidance on usage, parameter details, and behavioral traits.
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. It only mentions 'datasource_path' implicitly via 'from an Excel or Hyper datasource', but fails to explain 'output_dir', 'resume_if_exists', 'authoring_mode', or 'force_new'. The default values are in schema but no semantic explanation.
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 ('Initialize') and identifies the resource ('guided authoring run') and source types ('Excel or Hyper datasource'). However, it doesn't clearly distinguish from sibling tools like 'resume_authoring_run' or 'reopen_authoring_stage', which are closely related.
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 does not provide any guidance on when to use this tool versus alternatives like 'resume_authoring_run' or 'reopen_authoring_stage'. There is no mention of prerequisites or context for use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Validate a workbook against the official Tableau TWB XSD schema (2026.1).
Checks whether the generated XML conforms to Tableau's published schema. Errors are informational — Tableau itself occasionally produces workbooks that deviate slightly from the schema — but recurring errors indicate structural problems worth fixing.
Args: file_path: Path to a .twb or .twbx file to validate. If omitted, validates the currently open workbook (in memory, before save).
Returns: PASS/FAIL summary with error details.
| Name | Required | Description | Default |
|---|---|---|---|
| file_path | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
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 discloses that errors are informational and that Tableau itself may produce deviations, which sets expectations for false positives. It does not detail performance or side effects, but the tool is read-only validation.
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 well-structured with a summary line, behavior note, and clear Args/Returns sections. It is concise at 9 lines, though the second paragraph could be slightly tighter.
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 single parameter, no annotations, and presence of an output schema (which handles return format), the description is complete. It covers purpose, usage nuance, parameter semantics, and expected 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%, but the description compensates by documenting the sole parameter 'file_path' with its type and behavior (null validates current open workbook). This adds meaning beyond the schema's anyOf/null/default.
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 (validate) and resource (workbook), specifies the schema version (2026.1), and distinguishes from siblings like 'analyze_twb' or 'diff_template_gap' by focusing on schema conformance rather than analysis or migration.
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 explains when to use (validate against schema) and provides context about errors being informational versus indicating structural problems. It does not explicitly mention alternatives among siblings but implies this is for schema validation specifically.
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. Dates show when Glama detected each change.
v0.18.1add_calculated_fieldadd_dashboardadd_dashboard_actionadd_parameteradd_worksheetanalyze_twbapply_twb_migrationapply_worksheet_refactorbuild_analysis_briefbuild_execution_planbuild_wireframeclone_worksheetconfigure_chartconfigure_chart_recipeconfigure_dual_axisconfigure_worksheet_styleconfirm_authoring_stagecreate_workbookdescribe_capabilitydiff_template_gapdraft_authoring_contractfinalize_analysis_brieffinalize_authoring_contractfinalize_wireframegenerate_layout_jsongenerate_workbook_from_runget_client_interaction_capabilitiesget_run_statusinspect_target_schemaintake_datasource_schemainteractive_stage_confirmationlist_authoring_runslist_capabilitieslist_dashboardslist_fieldslist_worksheetsmigrate_twb_guidedopen_workbookpreview_twb_migrationpreview_worksheet_refactorprofile_twb_for_migrationpropose_field_mappingremove_calculated_fieldreopen_authoring_stageresume_authoring_runreview_authoring_contractreview_authoring_contract_for_runsave_workbookset_excel_connectionset_hyper_connectionset_mysql_connectionset_tableauserver_connectionset_worksheet_captionset_worksheet_hiddenstart_authoring_runvalidate_workbookMost tools target distinct actions like adding fields, configuring charts, or managing authoring runs. However, tools like 'build_analysis_brief' and 'finalize_analysis_brief' could be confused, and 'review_authoring_contract' vs 'review_authoring_contract_for_run' have overlapping purposes.
Tools predominantly use verb_noun pattern (e.g., add_calculated_field, open_workbook), but there are inconsistencies like 'interactive_stage_confirmation' (adjective_noun) and 'profile_twb_for_migration' (verb_noun_preposition). The naming is readable but not fully consistent.
With 56 tools, the server is overly large for a focused authoring assistant. Many tools are specialized for guided workflows, making the surface feel bloated. A smaller, more focused set would be more coherent.
The tool set covers a broad range of workbook operations: creation, editing, validation, migration, and connection management. Minor gaps exist, such as lacking direct tool for deleting worksheets or dashboards, but the overall lifecycle is well-covered.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Generate Tableau .twb/.twbx workbooks: 47 tools for charts, dashboards, rules, CSV pipelines.
Open, inspect, filter, edit and convert xlsx and csv files from your AI chat. Processing is local.
AI access to Quadratic spreadsheets: open files, run Python/SQL, query connected databases.
Renders interactive Chart.js charts and dashboards inline in AI conversations.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/aidatacooper/cwtwb'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
