The Dataverse MCP Server provides AI agents with structured access to Microsoft Dataverse and Power Platform environments across 14 functional categories:
Environment & Identity: List Power Platform environments, identify the authenticated caller, discover OData EntitySet names, and check user privileges and record-level access rights.
Data Operations: Query records with OData filters or FetchXML (joins, aggregation, paging), retrieve single records by GUID, count and aggregate records, execute bulk $batch operations, create/update/delete/upsert records, associate/disassociate records, merge duplicates, and swap connection references in cloud flows.
Schema & Metadata: List, inspect, create, update, and delete tables, columns, relationships, choices (option sets), and alternate keys; publish schema customizations.
Solutions & ALM: List, get, create, update, export, import, stage/upgrade, and clone solutions; manage publishers and solution components; track import jobs, view solution history, and analyze dependencies.
Security Administration: List/get security roles, teams, users, and business units; assign/remove roles; audit user access and effective privileges; manage team memberships; enable/disable users.
Audit & History: Query audit records, retrieve before/after details for audit entries, and get full change history for any record.
Plug-in Registration & Diagnostics: List and manage plug-in assemblies, packages, types, steps, and step images; view performance statistics; configure trace log verbosity and query trace logs.
Custom APIs: List, get, create, update, and delete Custom APIs and their request parameters/response properties.
Forms & Views: List, inspect, validate, create, and update model-driven app forms and saved views; add/remove form controls and view columns.
Model-Driven Apps: List, get, validate, create, update, and publish apps; manage app components, sitemaps, and security role assignments.
Cloud Flows & Classic Processes: List, enable/disable cloud flows; list and activate/deactivate classic processes (workflows, business rules, actions, BPFs).
Connection References & Environment Variables: List, get, create, update, and delete connection references, environment variable definitions, and values.
Web Resources: List, get, create, update, delete, and publish web resources (JS, HTML, CSS, images, etc.).
Async Jobs: List, inspect, and cancel system jobs (async operations).
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Dataverse MCP Server list the top 10 active accounts"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
An MCP server that gives AI agents structured access to Microsoft Dataverse — query records, bulk upsert data, inspect metadata, manage schema, analyze component dependencies, manage model-driven app forms, views, and apps, administer security roles, teams, and users, audit user access, manage plug-in trace logging, manage custom APIs, and explore Power Platform environments.
Built with MCPServer (mcp.server.mcpserver), httpx, and the Dataverse OData v4.0 Web API. Communicates over stdio and works with Claude, GitHub Copilot, and any MCP-compatible client.
1. Install uv
pip install uv2. Configure — add to your MCP client config:
Claude (claude_desktop_config.json or .claude/settings.json):
{
"mcpServers": {
"dataverse-mcp": {
"command": "uvx",
"args": ["dataverse-mcp"],
"env": {
"DATAVERSE_AUTH_TYPE": "interactive"
}
}
}
}GitHub Copilot (.vscode/mcp.json):
{
"servers": {
"dataverse-mcp": {
"type": "stdio",
"command": "uvx",
"args": ["dataverse-mcp"],
"env": {
"DATAVERSE_AUTH_TYPE": "interactive"
}
}
}
}3. Sign in
On first use the server opens a browser for interactive sign-in. The session is cached and reused across restarts (see DATAVERSE_TOKEN_CACHE_PERSIST), so you are not prompted again while the token is valid.
That's it. Your AI agent can now query your Dataverse environments.
Prefer your existing Azure CLI session instead? Set
DATAVERSE_AUTH_TYPEtoazure_cliand runaz login.
Related MCP server: Dataverse MCP Server
uvx is provided by uv. Install it first if you don't have it:
pip install uvRequires the MCP Python SDK
>=2.0.0. Versions up to and including 3.7.0 require SDK 1.x and will not start against 2.x — the SDK removedmcp.server.fastmcpin 2.0.0, so an older release installed today fails at import withModuleNotFoundError: No module named 'mcp.server.fastmcp'. Becauseuvxignores lockfiles and resolves the latest SDK, use 3.8.0 or later.
uvx dataverse-mcpuvx downloads and runs the package in an isolated environment — no virtual environment management required.
git clone https://github.com/ryanmichaeljames/dataverse-mcp.git
cd dataverse-mcp
uv syncThis creates .venv. Use the local source MCP config shown in Client Setup to point your client at it. No build step required — code changes are picked up on the next server start.
Set these in the env block of your MCP server entry. This project does not use a .env file.
Variable | Default | Description |
|
| Authentication method: |
|
| Set to |
|
| Set to |
| — | Comma-separated list of tool categories to register (e.g., |
| — | Comma-separated list of allowed environment hostnames (e.g., |
|
| When |
| — | Optional directory that confines the solution export/import file paths ( |
|
| Maximum seconds to wait for a credential acquisition (e.g., |
|
| Controls whether |
|
| When |
| — | Optional name that isolates the |
Leaving DATAVERSE_WHITELIST unset is risky. Tools accept a dataverse_url per call, and the server mints a bearer token for whatever environment is supplied. Without a whitelist, a compromised or misbehaving agent can direct your credentials at any Dataverse environment. Set DATAVERSE_WHITELIST to the specific environment hostnames you intend to use so the server rejects everything else. On shared or multi-tenant hosts, also set DATAVERSE_REQUIRE_WHITELIST=true so the server fails closed rather than minting tokens when the whitelist is accidentally left empty.
Method | Description |
| Opens a browser for interactive sign-in. Supports MFA and per-account isolation, and needs no separate CLI login. The session persists across server restarts (see |
| Uses your active |
Interactive auth persistence. When DATAVERSE_TOKEN_CACHE_PERSIST=true (the default), the MSAL token cache is stored on disk using your OS secret store (Windows DPAPI, macOS Keychain, Linux libsecret). On headless Linux without libsecret, the first token acquisition will fail fast with an error. Set DATAVERSE_TOKEN_CACHE_ALLOW_UNENCRYPTED=true to permit a plaintext cache on those hosts, and see the security warning for that variable above.
Running multiple tenants/accounts at once. The default cache and sidecar filenames are shared per host, so two interactive sessions signed in to different tenants/accounts would overwrite each other's pinned account. Give each session a distinct DATAVERSE_TOKEN_CACHE_PROFILE (e.g., prod, dev) to keep their caches and AuthenticationRecord sidecars separate.
Register two server entries, each with its own DATAVERSE_TOKEN_CACHE_PROFILE. The profile is a tenant-wide cache key — each entry signs in once (its own browser prompt) and then restarts silently as its own account, while tools still receive the specific dataverse_url per call. The profiles never collide.
Claude (claude_desktop_config.json or .claude/settings.json):
{
"mcpServers": {
"dataverse-prod": {
"command": "uvx",
"args": ["dataverse-mcp"],
"env": {
"DATAVERSE_AUTH_TYPE": "interactive",
"DATAVERSE_TOKEN_CACHE_PROFILE": "prod"
}
},
"dataverse-dev": {
"command": "uvx",
"args": ["dataverse-mcp"],
"env": {
"DATAVERSE_AUTH_TYPE": "interactive",
"DATAVERSE_TOKEN_CACHE_PROFILE": "dev"
}
}
}
}GitHub Copilot (.vscode/mcp.json):
{
"servers": {
"dataverse-prod": {
"type": "stdio",
"command": "uvx",
"args": ["dataverse-mcp"],
"env": {
"DATAVERSE_AUTH_TYPE": "interactive",
"DATAVERSE_TOKEN_CACHE_PROFILE": "prod"
}
},
"dataverse-dev": {
"type": "stdio",
"command": "uvx",
"args": ["dataverse-mcp"],
"env": {
"DATAVERSE_AUTH_TYPE": "interactive",
"DATAVERSE_TOKEN_CACHE_PROFILE": "dev"
}
}
}
}Each profile maps to one tenant/account sign-in; agents pass the target dataverse_url on each tool call. Omit DATAVERSE_TOKEN_CACHE_PROFILE (or leave it empty) for a single-tenant setup — the original shared cache filenames are used.
Most write and delete tools are not registered by default, so they do not appear to the agent until explicitly enabled. One exception is dataverse_execute_batch, which is always visible but only allows GET requests unless DATAVERSE_ALLOW_WRITE=true. This prevents accidental mutations when you only need to read or inspect data while still allowing safe batch reads by default.
{
"servers": {
"dataverse-mcp": {
"type": "stdio",
"command": "uvx",
"args": ["dataverse-mcp"],
"env": {
"DATAVERSE_AUTH_TYPE": "interactive",
"DATAVERSE_ALLOW_WRITE": "true",
"DATAVERSE_ALLOW_DELETE": "true"
}
}
}
}Each flag is independent — set only DATAVERSE_ALLOW_WRITE=true to allow creates and updates while keeping deletes disabled.
These behaviors are built in and need no configuration:
Automatic retries — requests throttled by Dataverse service-protection limits or hitting transient gateway errors are retried automatically; read-only requests are also retried on timeouts and connection failures.
Response size cap — responses larger than 5 MB are replaced with an error asking the agent to narrow the query with select, top, or filter.
Consistent errors — every tool returns JSON; failures have the shape {"error": true, "message": "..."} with the Dataverse error code included and the message capped in length.
Server-side paging — list tools request right-sized pages from Dataverse instead of full 5,000-record pages.
Add to claude_desktop_config.json:
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
{
"mcpServers": {
"dataverse-mcp": {
"command": "uvx",
"args": ["dataverse-mcp"],
"env": {
"DATAVERSE_AUTH_TYPE": "interactive"
}
}
}
}Add via the CLI:
claude mcp add dataverse-mcp --env DATAVERSE_AUTH_TYPE=interactive uvx dataverse-mcpOr add directly to .claude/settings.json (project) or ~/.claude/settings.json (user):
{
"mcpServers": {
"dataverse-mcp": {
"command": "uvx",
"args": ["dataverse-mcp"],
"env": {
"DATAVERSE_AUTH_TYPE": "interactive"
}
}
}
}{
"mcpServers": {
"dataverse-mcp-local": {
"command": "C:\\path\\to\\dataverse-mcp\\.venv\\Scripts\\python.exe",
"args": ["-m", "dataverse_mcp.server"],
"env": {
"PYTHONPATH": "C:\\path\\to\\dataverse-mcp\\src",
"DATAVERSE_AUTH_TYPE": "interactive"
}
}
}
}Add to .vscode/mcp.json in your project root.
{
"servers": {
"dataverse-mcp": {
"type": "stdio",
"command": "uvx",
"args": ["dataverse-mcp"],
"env": {
"DATAVERSE_AUTH_TYPE": "interactive"
}
}
}
}{
"servers": {
"dataverse-mcp-local": {
"type": "stdio",
"command": "C:\\path\\to\\dataverse-mcp\\.venv\\Scripts\\python.exe",
"args": ["-m", "dataverse_mcp.server"],
"env": {
"PYTHONPATH": "C:\\path\\to\\dataverse-mcp\\src",
"DATAVERSE_AUTH_TYPE": "interactive"
}
}
}
}A single server instance can target any Dataverse org — pass dataverse_url on each tool call:
{
"dataverse_url": "https://yourorg.crm.dynamics.com",
"entity_set_name": "accounts",
"select": ["name", "accountid"],
"top": 10
}dataverse_url is required on every tool call. Use dataverse_list_environments to discover available environments if you do not yet know the URL.
200 tools grouped by domain below. Every tool returns JSON and requires dataverse_url on each call.
The Gate column shows when a tool is registered:
Gate | Meaning |
| Always registered (reads and safe queries). |
| Registered only when |
| Registered only when |
dataverse_execute_batchisdefaultbut rejects non-GET operations unlessDATAVERSE_ALLOW_WRITE=true.
Use DATAVERSE_TOOLS to register only the tool categories your agent needs. This shrinks the visible tool list and reduces token overhead.
Category | Tools | Description |
| 24 | Environment introspection, effective org settings, all record CRUD, and unpublished-customization reads (always registered) |
| 35 | Table/column/relationship/choice/alternate-key metadata, component customizability pre-flight, environment language codes |
| 21 | Solution and publisher management, solution components, history, import/export ALM, import diagnostics, dependency analysis |
| 8 | Cloud flow + classic process listing and activate/deactivate |
| 6 | Model-driven form management |
| 7 | Saved query / view management |
| 10 | Canvas and model-driven app management |
| 5 | Connection reference management |
| 8 | Environment variable definitions and values |
| 33 | Plugin assemblies, types, steps, step images, packages, trace logs |
| 22 | Security roles and their privileges, teams and their privileges, the environment-wide privilege catalogue, users, business units, record access origin, record shares, composite access audit, record- and column-level audit history |
| 3 | Async operation (system job) monitoring and cancellation |
| 5 | Web resource (JS/HTML/CSS/image) CRUD — gated, not always-on |
| 13 | Custom API, request parameter, and response property management |
core is always registered even when not listed. When DATAVERSE_TOOLS is unset or empty, all categories register (current default behaviour). Category gating composes with DATAVERSE_ALLOW_WRITE and DATAVERSE_ALLOW_DELETE: a tool registers only when its category is enabled AND its write/delete flag (if any) is set.
Tool | Gate | Description |
| default | List Power Platform environments accessible to the caller |
| default | Return the caller's |
| default | Fingerprint the environment — server version, organization identity, instance type, service endpoints, installed-solution count |
| default | Read one setting's final computed value via |
| default | List OData EntitySet names from the service document |
| default | List security privileges assigned to a user |
| default | Check a user's access rights to a specific record |
Tool | Gate | Description |
| default | List security roles, optional filter and pagination |
| default | Get one security role by GUID |
| default | List the privileges assigned to a security role via |
| default | Answer why a principal has access to one record — role, ownership, share, business-unit hierarchy, team membership — via |
| default | List teams, optional filter and pagination |
| default | Get one team by GUID |
| default | Answer "what can this team actually do?" via the entity-bound |
| default | List the privileges defined in the environment from the |
| default | List everyone one record was shared with, merging |
| default | List system users, optional filter and pagination |
| default | Get one system user by GUID |
| default | List business units, optional filter and pagination |
| default | Composite report: user identity, direct roles, team memberships + team roles, effective privileges, optional record-level access check |
| default | Query the |
| default | Get full before/after detail for a single audit record via the bound |
| default | Retrieve the full audit change history for a single record via |
| default | Audit trail for one column of one record via |
| write | Assign a security role to a user or team |
| write | Add one or more users to a team |
| write | Enable or disable a system user ( |
| delete | Remove a security role from a user or team |
| delete | Remove one or more users from a team |
Tool | Gate | Description |
| default | List system jobs (asyncoperations), optional filter by statecode/statuscode/operationtype |
| default | Get one system job by GUID |
| write | Cancel a running or waiting system job (PATCH statecode=3/statuscode=32) |
Tool | Gate | Description |
| default | List web resources; optional filter by type and/or name substring |
| default | Get one web resource by GUID; |
| write | Create a web resource (name, type, base64 content); call |
| write | PATCH content, display name, or description; call |
| delete | Permanently delete an unmanaged web resource by GUID |
Tool | Gate | Description |
| default | Query records with filter, select, orderby, expand, top |
| default | Execute a FetchXML query (joins, aggregation, paging cookie) |
| default | Pre-flight a FetchXML query via |
| default | Get one record by entity set name and GUID |
| default | Read the unpublished (draft) definition of one customization record via |
| default | Count rows in a table, optional filter |
| default | Approximate row counts for up to 50 tables in one call ( |
| default | Aggregate (sum, avg, min, max, countdistinct) with optional grouping |
| default | Run up to 1,000 OData operations in one |
| write | Upsert many records via |
| write | Create a record and return its new GUID |
| write | Partially update a record (PATCH) |
| write | Swap a connection reference logical name inside a cloud flow's |
| write | Associate two records via a collection-valued navigation property |
| write | Merge a subordinate record into a target (account, contact, lead, incident) |
| delete | Permanently delete a record |
| delete | Remove an association between two records |
Tool | Gate | Description |
| default | List tables, optional metadata filter |
| default | Get full schema details for a table |
| default | List columns for a table, optional type filter |
| default | Get full metadata for one column, including type-specific properties |
| default | Report the environment's language codes (LCIDs), reconciling |
| default | Pre-flight check via |
| write | Create a custom table (ownership type, primary name attribute) |
| write | Update a table's display name or description |
| write | Add a typed column to a table (supports Memo, Boolean with custom labels, and Picklist/MultiSelectPicklist bound to a global choice) |
| write | Replace a column via full PUT (fetch with |
| write | Publish schema changes via |
| delete | Permanently delete a custom table and all its data |
| delete | Permanently delete a custom column and all its data |
Tool | Gate | Description |
| default | List relationships for a table or the whole environment |
| default | Get full metadata for one relationship by schema name |
| default | Answer "is this table eligible?" — a per-table boolean for one table you can already name; use |
| default | Answer "which tables are eligible?" — enumerate the tables that may take a relationship role via |
| write | Create a 1:N relationship and its lookup column |
| write | Create an N:N relationship and its intersect table |
| write | Create a polymorphic lookup referencing multiple tables |
| write | Replace a relationship via full PUT (fetch with |
| delete | Delete a custom relationship by MetadataId |
Tool | Gate | Description |
| default | List global choices (option sets) |
| default | Get a global choice and its options by name or MetadataId |
| default | Get options for a Picklist or MultiSelectPicklist column |
| write | Create a global choice with initial options |
| write | Replace a global choice via full PUT (fetch with |
| write | Add an option to a global or local choice |
| write | Update the display label of an option |
| write | Reorder all options in a choice |
| delete | Delete a global choice by logical name |
| delete | Remove one option from a global or local choice |
Tool | Gate | Description |
| default | List |
| write | Create an alternate key by |
| delete | Remove an alternate key by logical name; drops the underlying SQL index |
Tool | Gate | Description |
| default | List solutions, optional filter and pagination |
| default | Get a solution by unique name or GUID |
| default | List components in a solution, optional type filter |
| default | Get one solution history record (import/upgrade/export operation) by GUID |
| default | List solution history records, optional filter by solution GUID or unique name; |
| write | Create a publisher with customization prefixes |
| write | Update publisher fields by GUID |
| write | Create a solution (publisher binding, version) |
| write | Update solution fields by GUID or unique name |
| write | Update only a solution's version |
| write | Add a component via |
| delete | Remove a component via |
| default | Export a solution as a base64 zip; write to disk via |
| write | Import a solution asynchronously via |
| write | Single-step solution upgrade via |
| write | Two-step apply-upgrade via |
| default | Get one importjob by GUID — returns progress, completedon, solutionname; add |
| default | Why did the import fail? — the platform's own human-readable results document for one importjob via |
| default | List importjobs, optional filter by solution unique name, ordered by createdon desc |
| write | Clone a solution as a patch via bound |
| default | Analyze component dependencies: |
Filesystem I/O note.
dataverse_export_solutioncan write the decoded .zip to a local path whenoutput_pathis supplied.dataverse_import_solutioncan read a local .zip wheninput_pathis supplied. Both paths are resolved on the machine running the MCP server. Useoutput_path/input_pathfor solutions larger than ~3 MB (the inline base64 threshold).
Tool | Gate | Description |
| default | Query cloud flows, optionally scoped to a solution |
| write | Enable one flow by workflow ID |
| write | Enable many flows in one |
| write | Disable one flow by workflow ID |
| write | Disable many flows in one |
| default | List classic processes (workflows, business rules, actions, BPFs) from the |
| write | Activate a classic process (sets statecode=1/Activated); idempotent |
| write | Deactivate a classic process (sets statecode=0/Draft); idempotent |
Tool | Gate | Description |
| default | List forms for a table, optional form type filter |
| default | Get a form's layout as a tabs → sections → controls tree |
| default | Validate FormXml against XSD; pass |
| write | Replace and publish a form's FormXml; returns |
| write | Add a column control to a form (auto-resolves classid) |
| write | Remove a column control by logical name |
dataverse_get_formreturns the published form. After any write above, read the draft back withdataverse_retrieve_unpublished(entity_set_name='systemforms') or publish first withdataverse_publish_customizations.
Tool | Gate | Description |
| default | List saved views (savedquery) for a table, optional query type filter |
| default | Get a view's FetchXml, LayoutXml, and column list |
| default | Validate a view's FetchXml and LayoutXml |
| write | Create a saved view with FetchXml and LayoutXml |
| write | Update a view's FetchXml, LayoutXml, name, or description |
| write | Add a column to a view's LayoutXml |
| write | Remove a column from a view's LayoutXml |
dataverse_get_viewreturns the published view. After any write above, read the draft back withdataverse_retrieve_unpublished(entity_set_name='savedqueries') or publish first withdataverse_publish_customizations.
Tool | Gate | Description |
| default | List apps; |
| default | Get an app's properties and components grouped by type |
| default | Validate an app via |
| write | Create an app (sitemap, components, validation, publish) |
| write | Update an app's name or description |
| write | Add tables, forms, views, charts, or BPFs to an app |
| write | Remove components from an app |
| write | Create or replace an app's navigation sitemap |
| write | Publish an app to make it visible to users |
| write | Associate or disassociate a security role with an app |
Tool | Gate | Description |
| default | List connection references, optional connector/status/OData filters |
| default | Get one by GUID or logical name |
| write | Create one, optional connection and solution association |
| write | Assign/clear connection, update fields, or associate with a solution |
| delete | Delete an unmanaged connection reference |
Tool | Gate | Description |
| default | List definitions with current values; optional solution filter or single-record name lookup (schema name / display name) |
| write | Create a definition and optional initial value |
| write | Update definition fields and/or upsert the current value |
| delete | Delete definition, value record, or both |
Tool | Gate | Description |
| default | Get value record(s) by value GUID, definition GUID, or definition name |
| write | Create a value record bound to a definition (by GUID or name) |
| write | PATCH an existing value record by value GUID, definition GUID, or definition name |
| delete | Delete a value record only (resets to default value) by value GUID, definition GUID, or definition name |
Tool | Gate | Description |
| default | List registered plug-in assemblies |
| default | Get one plug-in assembly |
| default | List NuGet plug-in packages |
| default | Get one plug-in package |
| default | List plug-in types (classes) in an assembly |
| default | Get one plug-in type |
| default | List SDK message processing step registrations |
| default | Get one processing step |
| default | List pre/post entity images on a step |
| default | Get one step image |
| default | List SDK messages (Create, Update, …) — reference |
| default | Get one SDK message |
| default | List SDK message filters (message/entity combos) — reference |
| default | Get one SDK message filter |
| write | Register a plug-in assembly |
| write | Update a plug-in assembly |
| write | Register a plug-in package |
| write | Update a plug-in package |
| write | Register a plug-in type |
| write | Update a plug-in type |
| write | Register an SDK message processing step |
| write | Update a processing step |
| write | Register a step image |
| write | Update a step image |
| delete | Delete a plug-in assembly |
| delete | Delete a plug-in package |
| delete | Delete a plug-in type |
| delete | Delete a processing step |
| delete | Delete a step image |
Tool | Gate | Description |
| default | Runtime performance stats (execution count, failure rate, crashes) per plug-in type |
| default | Get org-wide trace log verbosity (off / exception / all) |
| default | List trace logs with filters (class, message, entity, operation, errors-only, time window) |
| write | Set org-wide trace log verbosity ( |
Tool | Gate | Description |
| default | List custom APIs, optional filter and pagination |
| default | Get one custom API by GUID, including its request parameters and response properties |
| write | Create a custom API (unbound, entity-bound, or entity collection-bound) |
| write | Update mutable fields of a custom API (display name, description, visibility, allowed step types) |
| delete | Permanently delete a custom API and its child parameters and properties |
| default | List request parameters for a custom API |
| write | Add a typed request parameter to a custom API |
| write | Update mutable fields of a request parameter |
| delete | Delete a request parameter |
| default | List response properties for a custom API |
| write | Add a typed response property to a custom API |
| write | Update mutable fields of a response property |
| delete | Delete a response property |
# Install dependencies
uv sync
# Run the MCP inspector (interactive testing)
uv run mcp dev src/dataverse_mcp/server.py
# Run the server directly
uv run python -m dataverse_mcp.server
# Compile check
uv run python -m py_compile src/dataverse_mcp/server.pyRestart the MCP server in VS Code after code changes to pick up the new source.
MIT
Independent community project. Not affiliated with, endorsed by, or supported by Microsoft. For the first-party runtime server, see Microsoft's Dataverse MCP Server.
"Dataverse" is a trademark of the President and Fellows of Harvard College. "Microsoft Dataverse" and "Power Platform" are trademarks of the Microsoft group of companies. Used here only to describe the systems this tool works with.
Group and aggregate Dataverse records with an OData $apply expression.
Use this for per-group questions (e.g. count by status, sum revenue by region). For a single total count use dataverse_count_records; for raw rows use dataverse_query_table. Works on up to 50,000 records. See the apply parameter for expression examples.
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. Description adds valuable behavioral context: works on up to 50,000 records, lookup fields cannot be used in groupby, and correct use of 'countdistinct'. No contradictions.
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?
Four sentences, front-loaded with purpose, each sentence adds value. No unnecessary words. Efficiently communicates key information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of an output schema (not shown) and thorough annotations, the description covers usage context, constraints (50k limit), and examples. No missing critical information 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 describes all parameters with coverage 0% (per context), but each parameter has a description in schema. Description adds examples for the apply parameter but does not elaborate on other params. Baseline 3 is appropriate as schema already provides 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 clearly states the tool groups and aggregates Dataverse records using OData $apply. It explicitly distinguishes from siblings: dataverse_count_records for single total count and dataverse_query_table for raw rows.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides clear when-to-use (per-group questions like count by status, sum by region) and when-not-to-use (single total count or raw rows), with explicit sibling tool alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Analyze dependencies for a Dataverse solution component.
Exposes three directions via the direction parameter:
blocking_delete: components that must be removed before this one can be deleted.
dependents: all components that reference/depend on this component.
required: all components this component requires to exist.
Use component_type integer codes (1=Entity, 2=Attribute, 61=WebResource, etc.) and the component's metadata GUID for component_id.
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description aligns with annotations (readOnlyHint, idempotentHint, etc.) and adds behavioral context by explaining the three dependency directions and the need for component_type and component_id. It does not contradict annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise (7 lines) and well-structured with bullet points, making it easy to scan. Every sentence earns its place without 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 the presence of an output schema, the description does not need to detail return values. It covers all necessary aspects: purpose, parameters, direction options, and example codes. The tool is adequately documented 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?
The description adds significant value beyond the input schema by explaining the meaning of component_type integer codes and providing a link to documentation. The schema's property descriptions are already present, but the description clarifies usage via examples and context for the direction parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: analyzing dependencies for a Dataverse solution component. It distinguishes from siblings by focusing on dependency analysis rather than listing or retrieving records, and elaborates on three specific dependency directions.
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 each direction parameter, providing clear context for selecting the appropriate analysis type. However, it does not explicitly state when not to use this tool or mention alternative tools that might be more appropriate for specific scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return a composite access report for a Dataverse system user.
Gathers in one call: user identity, direct security roles, team memberships (with each team's roles), and optionally effective privileges and record-level access rights. Resolves all type codes to human-readable names.
Provide either user_id (GUID) or user_domain_name (e.g. 'user@contoso.com'). Optionally provide target_entity_set_name + target_record_id to include a record-level access check.
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint, idempotentHint, and destructiveHint. The description adds behavioral details: it resolves type codes, gathers multiple data in one call, and optionally includes privileges and record-level checks. No contradictions with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise (4 sentences) and well-structured: first sentence states purpose, second lists components, third mentions type resolution, fourth provides usage. Every sentence adds value without 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?
The description covers the tool's purpose, what it returns, and how to use parameters. It does not mention prerequisites or limitations (e.g., required permissions), but the output schema covers return details. Adequate for the tool's complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already contains thorough descriptions for each parameter (e.g., mutual exclusivity of user_id and user_domain_name). The tool description adds context about the composite nature but does not significantly enhance parameter meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns a composite access report for a Dataverse system user, listing specific components (identity, roles, team memberships, optionally privileges and record-level access). It distinguishes from sibling tools by positioning itself as a comprehensive single-call audit.
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 explicit instructions on parameter usage (user_id or user_domain_name, optional target_entity_set_name+target_record_id) and includes_privileges. However, it does not explicitly state when to use this composite tool versus individual sibling tools (e.g., get_user, retrieve_user_privileges).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Pre-validate whether a table supports a specific relationship role before creating a relationship.
Only call this immediately before dataverse_create_one_to_many_relationship or dataverse_create_many_to_many_relationship — do not use for general queries or data reads. Returns eligible (bool) for the requested check_type (see check_type field for valid values).
This tool answers "is THIS ONE table OK?" — a boolean about a table you can already name. To answer "WHICH tables are OK?" — the enumeration, when you do not yet know which table to point at — use dataverse_get_valid_relationship_entities, whose role values mirror this tool's check_type values one for one.
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds the behavioral context that this is a pre-validation step returning a boolean 'eligible' for the requested check_type. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact, front-loading the primary purpose in the first sentence, then providing usage timing, return type, and sibling differentiation in subsequent sentences. No filler or redundant content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the strong annotations and existing output schema, the description is complete for its intended pre-validation use. It explains when to use it, what it returns, and which alternative to use when the table is unknown, covering all necessary 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% from the tool description; it only points to 'check_type field for valid values' and does not describe dataverse_url or table_logical_name. Although the schema itself contains detailed descriptions, the description fails to compensate for the low coverage, adding minimal 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 the tool pre-validates whether a table supports a specific relationship role with a clear verb and resource. It distinguishes itself from sibling dataverse_get_valid_relationship_entities by contrasting 'is THIS ONE table OK?' (boolean check) versus 'WHICH tables are OK?' (enumeration).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly says to call only immediately before dataverse_create_one_to_many_relationship or dataverse_create_many_to_many_relationship, and not for general queries or data reads. It also names dataverse_get_valid_relationship_entities as the alternative for when the specific table is unknown.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Count records in a table (optionally filtered) and return only the integer total.
Use this instead of dataverse_query_table when you need a number, not rows. For per-group counts (e.g. count by status) use dataverse_aggregate_table. The total is capped at 5,000 by Dataverse.
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint, idempotentHint, not destructive. Description adds the 5,000 cap and confirms only integer returned, providing additional behavioral context beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, front-loaded with purpose, no redundant information. Efficiently conveys when to use and key constraint (cap).
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With annotations and output schema present, the description is sufficient: it explains the output (integer total) and the cap. No missing details for a simple count tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema descriptions provide parameter details (e.g., filter expression, URL, entity set name). The tool description does not add parameter semantics, but the schema covers them, so baseline of 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 counts records in a table and returns only the integer total. It distinguishes from dataverse_query_table (returns rows) and dataverse_aggregate_table (per-group counts).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly tells when to use this tool over siblings: use instead of dataverse_query_table when you need a number, not rows; use dataverse_aggregate_table for per-group counts. Also mentions the 5,000 cap.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Execute bulk or atomic multi-operation reads and writes via the OData $batch endpoint.
Use this for bulk record operations or when multiple writes must succeed or fail together. For single-record writes use dataverse_create_record / dataverse_update_record / dataverse_delete_record instead. For metadata/schema changes use the dataverse_create_*/update_*/delete_* metadata tools.
POST/PUT/PATCH operations require DATAVERSE_ALLOW_WRITE=true; DELETE operations require DATAVERSE_ALLOW_DELETE=true. Group operations with the same change_set_id to run them atomically (all-or-nothing, up to 1,000 operations per request). Returns per-operation results [{index, status_code, body}].
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations (readOnlyHint=false, destructiveHint=false), the description discloses important behavioral traits: the need for specific environment variables for write/delete operations, atomic execution with change_set_id, a maximum of 1,000 operations per request, and the return format including per-operation results.
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, well-structured paragraph that front-loads the purpose, then provides usage guidelines, requirements, and return format. Every sentence adds value without redundancy, making it concise 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 complexity of batch operations, the description covers all critical aspects: purpose, when to use, environment variable requirements, atomicity, max operations, and return format. It is complete enough for an agent to understand and invoke the tool 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 already includes detailed descriptions for each parameter (e.g., 'operations' lists minItems, max 1000; 'continue_on_error' explains behavior). The description adds value by explaining the concept of change_set_id for atomicity and the return format, which is not in the schema. Given that the schema itself is well-documented, the description provides complementary high-level context.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Execute bulk or atomic multi-operation reads and writes via the OData $batch endpoint.' It distinguishes from sibling tools by explicitly naming alternatives for single-record writes and metadata changes, and highlights the atomicity feature.
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 explicit guidance on when to use this tool (bulk operations, atomic writes) and when not to (single-record writes, metadata changes), referencing specific sibling tools. It also specifies requirements like DATAVERSE_ALLOW_WRITE and DATAVERSE_ALLOW_DELETE environment variables, and explains atomic grouping via change_set_id.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Execute a FetchXML query against a Dataverse table and return matching records.
FetchXML supports complex joins (link-entity), aggregation, and queries that OData $filter cannot express. Use dataverse_query_table for simple OData queries. Use dataverse_get_entity_sets to discover entity_set_name; the entity_set_name must match the root logical name's collection name.
FetchXML uses paging cookies (not @odata.nextLink). This tool returns one page plus paging metadata (has_more, paging_cookie) so the caller can page if needed.
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate read-only and idempotent. Description adds paging behavior (cookies, one page + metadata) and differences from OData. No contradictions.
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?
Four sentences, front-loaded with the main purpose, no redundant or extra words. Efficiently conveys key information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of output schema and annotations, the description covers all essential context: paging, sibling tool differentiation, and entity name discovery. No 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?
Description does not mention any parameters despite 0% schema description coverage. However, the input schema provides descriptions for each parameter. The description misses an opportunity to add meaning beyond the schema, but schema covers it. Score 2 due to missing parameter help.
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 executes a FetchXML query and returns records. It clearly distinguishes from dataverse_query_table for simple OData and provides guidance to discover entity_set_name.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit usage guidance: suggests using dataverse_query_table for simple queries and dataverse_get_entity_sets for entity name discovery. Also clarifies FetchXML supports complex joins and aggregation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Export a Dataverse solution as a base64-encoded zip.
Calls the ExportSolution unbound action. Large solutions (>~3 MB base64) must be saved to disk via output_path — supply a local filesystem path and the server writes the decoded .zip there, returning metadata only (no base64 in the response). Small solutions are returned inline when output_path is omitted. This tool is read-only for the org (no mutations); writing a local .zip when output_path is set is local I/O only and does not require DATAVERSE_ALLOW_WRITE.
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and destructiveHint; the description adds valuable behavioral details: file size threshold (~3 MB), local I/O behavior, and clarification that no DATAVERSE_ALLOW_WRITE permission is needed for disk writes. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is succinct (two paragraphs) and front-loaded with the core purpose. Every sentence adds value, no redundant or verbose statements.
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 many parameters and an output schema. The description covers the main behavioral aspect (inline vs disk) but does not explain the boolean flags for export settings. For a moderately complex tool, 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?
With schema description coverage at 0%, the description must compensate. It only explains the output_path parameter and its inline/disk behavior. Other important parameters (solution_name, managed, export flags) are not described, leaving the agent to rely on schema descriptions 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 clearly states the tool's purpose: 'Export a Dataverse solution as a base64-encoded zip.' It specifies the action (ExportSolution unbound action) and differentiates from sibling tools that are primarily 'get' or 'list' operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use output_path for large solutions and notes the tool is read-only. However, it does not explicitly exclude alternative tools or mention when not to use this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a model-driven app's properties and its current component list.
Returns app metadata and components grouped by type (Entity, View, Form, Sitemap, etc.) via RetrieveAppComponents. Use dataverse_list_apps to find app IDs. Call this before any write to confirm current component state.
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and openWorldHint. Description adds that it returns metadata and components grouped by type, providing behavioral context beyond annotations. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, each serving a distinct purpose: stating purpose, directing to prerequisite tool, and advising usage timing. Front-loaded with key 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 output schema exists, the description sufficiently covers purpose, input provenance, and usage timing. No missing critical information for a read-only retrieval 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?
Input schema includes descriptions for both parameters, but context reports 0% coverage. Description adds value by guiding use of dataverse_list_apps for finding app_ids, but does not elaborate on dataverse_url or app_id format beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the verb 'Get', the resource 'model-driven app', and what it returns (properties and component list grouped by type). References specific API (RetrieveAppComponents) and distinguishes from sibling dataverse_list_apps.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly directs to use dataverse_list_apps to find app IDs and advises calling this tool before any write operation. Does not explicitly state when not to use, but context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieve a single asyncoperation (system job) record by its GUID.
Returns the full record including name, operationtype, statecode, statuscode, message, friendlymessage, startedon, completedon, and _regardingobjectid_value. Also includes statecode_label and statuscode_label for human readability.
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds value by listing the returned fields (e.g., name, operationtype, statecode), which is beyond the annotations but does not disclose potential rate limits or auth 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 two sentences, front-loaded with the primary purpose, and no extraneous information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple and has an output schema, so the description is adequate but lacks usage guidelines and parameter context. It lists many return fields, which compensates partially for the missing output schema display.
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% per context, and the description does not add any detail beyond the schema's parameter descriptions. It only mentions 'by its GUID' without elaborating on parameter usage or formats.
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 'Retrieve' and the resource 'asyncoperation (system job) record by its GUID', distinguishing it from sibling tools like dataverse_list_async_operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when you have a specific GUID, but does not explicitly state when to use this tool vs alternatives like dataverse_list_async_operations, nor does it mention prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieve the audit trail for ONE COLUMN of ONE RECORD — who changed this field.
The column-scoped sibling of dataverse_retrieve_record_change_history, which returns every change to the record across all audited columns. Use this one when the question is about a single field ('when did this account's creditlimit last change, and to what?'); it answers from the server rather than making you filter a whole record's history client-side.
MIND THE SINGULAR/PLURAL SPLIT — this tool takes the SAME TABLE TWICE, under two different names, and they are NOT interchangeable:
entity_set_name — the PLURAL collection name ('accounts'). This is the only one sent to the function, inside the target EntityReference.
table_logical_name — the SINGULAR logical name ('account'). Never sent to the function; used only by the audit-configuration probes described below, which address table metadata by LogicalName. Both are required because the plural cannot be derived from the singular (or vice versa: 'webresource' -> 'webresourceset'), and it cannot be looked up either — $filter on the root EntityDefinitions collection is refused with HTTP 400 [0x80060888]. Use dataverse_get_entity_sets to confirm the plural.
ON A 404, READ THE ERROR CODE — DO NOT ASSUME WHICH FAILURE IT IS. Live-confirmed on this function, and the older warning that a missing record and a wrong entity set were indistinguishable was wrong:
a well-formed but NONEXISTENT record id with the CORRECT plural entity set returns HTTP 200, not a 404. The function did not check that the record exists, so a bogus GUID (or a deleted record) simply yields zero changes and the audit_configuration diagnosis below. A successful empty answer is therefore never proof that the record is there.
a VALID id with the WRONG (singular) entity set returns HTTP 404 [0x80060888] "Resource not found for the segment ''" — which NAMES the bad segment. That message is the singular-for-plural slip, not a missing record: fix the entity set name rather than hunting a deleted row. Do NOT read those two as an exhaustive split. On the sibling function RetrieveRecordChangeHistory, a sweep of 15 entity sets found a THIRD outcome — [0x80048d02] from a CORRECT plural entity set ('audits'), meaning the row really was absent, i.e. some entity sets DO validate the target. That sweep was run against the record-scoped function, not this one, so it is not confirmed here; it is reason enough to read the code that actually came back rather than trust a two-case rule. THE ALL-ZERO GUID IS HANDLED DIFFERENTLY BY THE TWO FUNCTIONS, live-confirmed. Passing 00000000-0000-0000-0000-000000000000 as record_id returns HTTP 200 with zero changes HERE, but the record-scoped dataverse_retrieve_record_change_history rejects the same id with HTTP 400 [0x80040203] "Expected non-empty Guid." That is Dataverse's own inconsistency between the two messages, not this server's. So an empty, successful answer from this tool can mean the caller passed a placeholder id — check the id before reading zero changes as a fact about the record.
AN EMPTY RESULT IS AMBIGUOUS, AND THIS TOOL RESOLVES IT. Audit rows are written only where auditing is enabled at organization AND table AND column level, so zero changes cannot by itself distinguish "nothing ever changed" from "auditing was never switched on". ONLY when there are zero changes, three probes fire concurrently and an audit_configuration block is attached carrying organization_audit_enabled / table_audit_enabled / column_audit_enabled and a diagnosis naming the OUTERMOST disabled level:
auditing_off_at_organization / auditing_off_at_table / auditing_off_at_column
auditing_enabled_no_changes_recorded — all three on, so the empty answer is real (auditing still only records changes made after it was switched on)
undetermined — a probe failed or returned an unreadable shape; the level is reported as null with the reason in probe_errors, and NOTHING is guessed.
NOT EVERY ENTRY IS A RESULT. Dataverse MAY add org-level audit-CONFIGURATION rows (auditing itself switched on or off) to a response. They arrive when an audit-configuration change falls inside the TARGET RECORD'S history window, so their presence and count VARY BY TARGET — a record created after the last such change gets none, while older records on the same org got four each, live-measured. audit_configuration_events_count: 0 is a normal, expected answer. They can arrive anywhere in the list and are identified by their SHAPE — no @odata.type, AuditRecord and nothing else, and an all-zero AuditRecord._objectid_value — never by their position. They are split out into audit_configuration_events (with audit_configuration_events_count) and are NOT counted as changes: audit_details, count and has_more cover this column's own changes only.
ENTRIES ARE POLYMORPHIC. Each change is returned verbatim, so read its @odata.type: a column-scoped call is expected to yield AttributeAuditDetail (AuditRecord, OldValue, NewValue, InvalidNewValueAttributes, plus AuditRecord.attributemask naming the changed columns) but nothing guarantees it — AuditDetail has several subtypes. An entry with an UNRECOGNIZED @odata.type is reported as a change, never quietly dropped; only the typeless AuditRecord-only shape with an all-zero objectid is treated as configuration. detail_types counts the @odata.type values actually present on the returned page, and unclassified_typeless_count reports how many entries carrying NO @odata.type were kept as changes — 0 on every response observed so far, and a non-zero value means this tool met an entry it could not name rather than that anything was lost.
RESPONSE SHAPE IS CHECKED, NOT ASSUMED. The entries sit TWO levels down (AuditDetailCollection -> AuditDetails). If that container is absent or is not a list, the tool returns normalized: false with the raw body — a missing container is NOT reported as "no changes".
PagingInfo is not sent, so the changes are trimmed client-side to top and has_more reports whether anything was cut. total_record_count appears ONLY when Dataverse supplied a real count: it is live-confirmed to arrive as -1 here both with and without PagingInfo, and a negative count is suppressed rather than passed on. It is never substituted with the number of returned entries.
URL form: GET /api/data/v9.2/RetrieveAttributeChangeHistory( Target=@t,AttributeLogicalName=@a) ?@t={"@odata.id":"accounts()"}&@a='name'
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Even with annotations declaring readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, the description goes far beyond them. It discloses that a nonexistent record ID returns HTTP 200 with zero changes, that a wrong singular entity set returns a specific 404, that empty results trigger audit-configuration probes, and that the response shape is checked rather than assumed. These are rich behavioral details not present in annotations and critical for correct use.
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 long but every section earns its place: each bolded segment addresses a distinct, verified behavior or pitfall. It is front-loaded with the purpose, then structured by topic (singular/plural, error codes, empty results, entry polymorphism, response shape, paging). The formatting with bullets and code snippets improves scannability without waste.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a complex tool with a nested input schema and an output schema, the description covers all critical aspects: the exact URL form, how to identify configuration events vs real changes, polymorphic entries, paging behavior, and the handling of ambiguous empty results. It even notes the differences from the sibling function. This leaves little to guess even for a caller unfamiliar with Dataverse audit APIs.
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 reported as 0%, so the description must carry the weight, and it does. It devotes a full section to the singular/plural split, explaining that entity_set_name is the plural, sent to the function, while table_logical_name is the singular, never sent and used only for probes. It also explains record_id semantics (must be well-formed GUID, all-zero GUID behavior) and column_logical_name, all adding meaning beyond the raw schema field 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 opens with a precise statement: 'Retrieve the audit trail for ONE COLUMN of ONE RECORD — who changed this field.' It then distinguishes itself from the sibling dataverse_retrieve_record_change_history by calling itself the 'column-scoped sibling,' making the scope and resource unmistakable.
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 explicitly says 'Use this one when the question is about a single field' and contrasts it with the record-scoped alternative. It also points to dataverse_get_entity_sets as a helper to confirm the plural entity set name, and gives detailed instructions on how to interpret 404 vs 200 responses, which is when-to-use guidance beyond the basics.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieve full details from a single audit record.
Calls the bound RetrieveAuditDetails function on the audit entity, returning a polymorphic AuditDetail. The most common subtype is AttributeAuditDetail which includes OldValue and NewValue (each containing the changed attribute values keyed by logical name) plus InvalidNewValueAttributes.
Common AuditDetail subtypes (identified by @odata.type):
AttributeAuditDetail — field changes with OldValue/NewValue
RelationshipAuditDetail — relationship association/disassociation
ShareAuditDetail — record sharing
RolePrivilegeAuditDetail — role privilege changes
UserAccessAuditDetail — user login/access events
Note: requires auditing enabled on the org. If auditing is disabled, Dataverse returns an HTTP error — check the error message for guidance.
URL form: GET /api/data/v9.2/audits()/Microsoft.Dynamics.CRM.RetrieveAuditDetails
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true, indicating a safe read operation. The description adds value by explicitly stating the auditing requirement and the polymorphic return types, which are important behavioral details not covered by annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise (5 sentences), well-structured, and front-loaded with the main purpose. It lists common subtypes in a clear, scannable format without 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 annotations and the presence of an output schema, the description covers all necessary context: purpose, return types (polymorphic subtypes), prerequisites (auditing enabled), and parameter origin. No gaps remain.
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 provides descriptions for both parameters (audit_id and dataverse_url). The description further clarifies that audit_id comes from listing or change history tools, adding helpful context beyond the schema 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 clearly states 'Retrieve full details from a single audit record' and explains the function call, subtypes, and scope. It distinguishes from sibling tools like dataverse_list_audit and dataverse_retrieve_record_change_history by focusing on full detail retrieval for a single audit record.
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 notes the prerequisite of auditing being enabled and the required audit_id format. It implicitly indicates when to use (when full details of a specific audit record are needed), but does not explicitly list when not to use or compare to siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get one GLOBAL choice (option set) — all option values, codes, and labels — by name or MetadataId.
For the options of a specific column's LOCAL choice use dataverse_list_choice_column_options instead. Provide either name or metadata_id; name takes precedence when both are given.
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint, idempotentHint, destructiveHint. Description adds value by clarifying global vs. local scope, precedence behavior, and that it returns all options. No contradictions found.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, no filler. Each sentence serves a distinct purpose: stating functionality and providing usage guidance with alternative. Highly efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Output schema exists, so return values need no explanation. Description covers core functionality, parameter usage, and distinguishes from siblings. Missing mention of consistency_strong and dataverse_url, but these are in schema. Complete enough for an agent to use 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?
Schema description coverage is 0%, so description must compensate. Description mentions 'by name or MetadataId' and precedence rule, covering two of four parameters. Does not address dataverse_url or consistency_strong, though schema descriptions fill part of the gap. Partial compensation earns baseline 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?
Description clearly states 'Get one GLOBAL choice (option set) — all option values, codes, and labels — by name or MetadataId.' It uses specific verb and resource, and distinguishes from sibling dataverse_list_choice_column_options by contrasting GLOBAL vs LOCAL.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use alternative tool: 'For the options of a specific column's LOCAL choice use dataverse_list_choice_column_options instead.' Provides precedence rule for name over metadata_id. Lacks broader context like prerequisites but offers clear decision guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List cloud flows in the Dataverse environment, optionally scoped to a solution.
Returns workflow records with statecode, statuscode, and category. Scope to a specific solution with solution_id or solution_unique_name.
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint, idempotentHint, and non-destructive. The description adds useful behavioral context by specifying the return of workflow records with statecode, statuscode, and category, and the scoping option. No contradictions with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the main purpose, and contains no extraneous information. Every word adds value, making it concise and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity and the presence of rich annotations and an output schema, the description is reasonably complete. It states the return type (workflow records with fields) and scoping options. However, it does not mention pagination or the top parameter, which are relevant for listing.
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?
Despite 0% schema description coverage (tool description does not detail most parameters), the description only covers solution_id and solution_unique_name for scoping. It omits required parameter dataverse_url and optional parameters top, filter, and select, leaving their semantics to the schema 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 clearly states the tool lists cloud flows in the Dataverse environment, with optional scoping to a solution. The verb 'List' and resource 'cloud flows' are specific, and the description distinguishes this tool from siblings like 'list_processes' by explicitly mentioning 'cloud flows'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context on scoping with solution_id or solution_unique_name, but lacks explicit guidance on when to use this tool versus alternatives (e.g., list_processes, query_table). It does not include when-not-to-use or compare with other listing tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get full metadata for a single column on a Dataverse table, including type-specific properties.
Returns all properties including MaxLength, Precision, RequiredLevel, Format, and IsValidForCreate. Use before updating a column — pass the returned object as full_definition to dataverse_update_column. For Picklist/MultiSelectPicklist option values use dataverse_list_choice_column_options.
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and idempotentHint. The description adds value by explaining the return value's role as a complete definition for updates and hinting at type-specific properties. It does not contradict annotations and provides behavioral context beyond structured fields.
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 at 70 words, structured in three focused paragraphs. It immediately states the purpose, then details return properties and usage context. Every sentence is informative with no 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 the presence of a robust input schema, annotations, and output schema, the description covers all necessary context: purpose, return content, update workflow linkage, and alternative tool for picklists. No gaps remain for an agent to use this tool 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 itself provides comprehensive descriptions for all parameters, including format hints like 'Use lowercase.' The tool description adds no additional parameter semantics beyond what the schema already covers, so a baseline score of 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 retrieves full metadata for a single column, including type-specific properties. It differentiates from sibling tools like dataverse_list_columns and dataverse_update_column by specifying its role as a prerequisite for updates and by directing picklist queries to a separate tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit guidance: 'Use before updating a column — pass the returned object as full_definition to dataverse_update_column.' Also advises using dataverse_list_choice_column_options for picklist option values, clearly indicating when not to use this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a single connection reference by GUID or logical name.
Returns the full record including the assigned connection ID, connector ID, status, and managed state. An empty connectionid means no connection has been wired up yet — use dataverse_update_connection_reference to assign one.
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses the returned fields and the significance of an empty connectionid, adding value beyond annotations that already indicate read-only and idempotent 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?
Two sentences: first states purpose and output, second provides a critical usage note. 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 output schema exists, the description appropriately covers the key behavioral aspect (empty connectionid) and the identification methods. Could mention prerequisites like permissions, but not essential for a read-only 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 description mentions retrieval by GUID or logical name, which aligns with parameters. However, the schema already provides descriptions for each parameter, so the description adds minimal extra 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 clearly states it retrieves a single connection reference by GUID or logical name, specifying the return fields. It distinguishes from sibling 'list_connection_references' by focusing on a single record.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit context on when to use update tool if connectionid is empty, guiding the agent. However, it does not explicitly state when not to use this tool (e.g., for multiple records).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieve a single Custom API record by its GUID, including expanded request parameters and response properties.
Returns all default columns plus:
CustomAPIRequestParameters (customapirequestparameterid, uniquename, name, type, isoptional)
CustomAPIResponseProperties (customapiresponsepropertyid, uniquename, name, type) The @odata.context key is stripped from the response.
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=true and destructiveHint=false. The description adds value by specifying that the response includes expanded CustomAPIRequestParameters and CustomAPIResponseProperties, and that @odata.context is stripped. This provides more detail than annotations alone, though it does not discuss authentication or rate limits.
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, with the main purpose stated upfront and additional details in bullet points. Every sentence is informative, and there is no redundant content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (two required parameters, single record retrieval) and the presence of an output schema, the description provides sufficient context. It explains the expanded fields and a notable transformation (@odata.context stripped). It does not cover potential errors or permissions, but these are standard for such a 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 already provides descriptions for both parameters (custom_api_id and dataverse_url). The description does not add new semantic information beyond mentioning 'by its GUID', which is already in the schema. With high schema coverage, baseline score 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 specifies that it retrieves a single Custom API record by GUID and expands request parameters and response properties. It distinguishes from siblings like dataverse_list_custom_apis (which lists all) and dataverse_get_record (which gets any record by table name).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for fetching a specific Custom API by GUID, but lacks explicit guidance on when to use this tool versus alternatives (e.g., dataverse_list_custom_apis) or when not to use it. No prerequisites or exclusions are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List OData EntitySet names from the Dataverse service document.
Use this to discover the correct entity_set_name for a table before querying records (e.g., 'account' → 'accounts', 'systemuser' → 'systemusers'). Faster and smaller than fetching $metadata. Filter with contains.
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and non-destructive. Description adds that it's faster/smaller than alternatives, which is useful behavioral context beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Concise: four sentences with no waste. Main purpose front-loaded, followed by usage guidance and a tip. Perfectly sized.
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?
Complete for a discovery tool with output schema. Covers purpose, usage context, filter mechanism, and performance benefit. No 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 provides full parameter descriptions (100% coverage by inspection). Description only mentions filter usage, adding minimal value over schema. Baseline score 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?
Clear verb ('list') and resource ('EntitySet names from the Dataverse service document'). Provides example mappings and distinguishes from siblings by focusing on discovery before querying.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use (before querying records) and why it's better than fetching $metadata. Mentions filtering capability, giving direct guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List environment variable definitions with their current values.
Each record includes the definition fields (schemaname, displayname, type, defaultvalue, description, ismanaged) plus the current value from the linked environmentvariablevalue record. The value field is null when no value record exists — fall back to defaultvalue in that case.
Provide name (schemaname or displayname) to look up a single definition. Schema name is tried first; display name is the fallback. name cannot be combined with solution_id or solution_unique_name.
Scope results to a specific solution with solution_id or solution_unique_name (componenttype 380 solutioncomponents query). Omit both to list all definitions in the environment.
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds significant behavioral context beyond the annotations, including the fallback to defaultvalue when value is null, the order of name lookup (schema name first, then display name), and the scoping mechanism via componenttype 380. No contradictions with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured, starting with the main purpose, then detailing output structure and parameter usage. It is concise for the amount of information conveyed, with no unnecessary repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that an output schema exists and the tool has few required parameters, the description provides enough detail about output format, parameter interactions, and edge cases (null value) to use the tool effectively. Minor gaps around pagination are covered by the schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema itself already describes each parameter, and the tool description reinforces key rules about mutual exclusivity and lookup order. However, it does not add new information for parameters like top or dataverse_url, and the low schema coverage (0%) means more responsibility on the description, which it partially meets.
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 environment variable definitions with their current values, and distinguishes itself from similar tools (e.g., dataverse_get_environment_variable_values) by detailing the merged output structure. It uses specific verbs and resources.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear guidance on when to use the name parameter versus solution scoping, and explicitly states that name cannot be combined with solution parameters. It does not directly compare with sibling tools, but the context is sufficient for correct usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get environment variable value record(s).
Provide exactly one targeting path:
value_id: fetch a single value record by its own GUID directly.
definition_id: list value record(s) linked to the given definition GUID.
name: resolve the definition by schema name or display name, then list its value record(s). Schema name is tried first; display name is the fallback.
Returns a list shape (records, count, has_more) in all cases for a consistent calling convention, even when a single record is expected. When no value record exists for a definition the list will be empty.
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare the tool as read-only and idempotent. The description adds important behavioral details: the return shape is always a list with records/count/has_more, even for single records, and describes behavior when no records exist. It also explains name resolution priority, providing transparency beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured: a one-line purpose, a bullet-like list of targeting paths, and a short note on return shape. Every sentence adds value, with no redundancy or fluff.
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 a comprehensive input schema and output schema, the description adequately covers usage scenarios, return shape, and edge cases (empty list). It could be improved by mentioning that the tool only retrieves values for a single definition at a time, but overall it is complete.
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 already provides descriptions for all parameters, including mutual exclusivity. The description adds value by explaining the order of name resolution (schema name first, then display name) and consolidating the targeting paths. With high schema coverage, the baseline is 3, and the additional context justifies a 4.
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 as retrieving environment variable value records, and distinguishes it from the sibling tool dataverse_get_environment_variables which retrieves definitions. It specifies three targeting paths, making the action and resource unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states that exactly one targeting path must be provided, outlines each path's use case, and notes the consistent return shape. However, it does not explicitly state when not to use this tool or compare it to alternatives beyond the sibling name, which prevents a perfect score.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a single Dataverse form's layout parsed as a structured JSON object.
Parses raw FormXml into a readable tabs → sections → controls tree so agents don't need to work with raw XML. Also returns formxml_backup (the raw XML string). Use dataverse_list_forms to discover form IDs.
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate read-only and idempotent behavior. The description adds value by explaining that the tool parses raw FormXml into a structured tree and returns raw XML backup, helping agents understand the output. No contradictions with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three concise sentences, front-loaded with purpose, followed by transformation detail and usage guidance. No extraneous content; every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of an output schema and clear annotations, the description covers all essential aspects: what the tool does, how it transforms data, and how to discover form IDs. No gaps in 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?
Input schema already provides clear descriptions for both parameters (form_id with GUID example, dataverse_url with example). The tool description does not add further parameter details, but the schema coverage is high, so baseline 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?
Clearly states it retrieves a single Dataverse form's layout parsed as structured JSON, distinguishing it from sibling tools like dataverse_list_forms which discover form IDs. The verb 'Get' and resource 'form layout' are specific.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly tells agents when to use this tool (to get parsed form layout instead of raw XML) and directs them to use dataverse_list_forms to discover form IDs, providing clear guidance on tool selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieve a single importjob record by its GUID to check import progress.
Returns progress (0–100), completedon, solutionname, and other tracking fields. The large result XML ('data' column) is excluded by default; set include_data=true to fetch it when diagnosing failures. Use dataverse_import_solution or dataverse_stage_and_upgrade_solution to start an operation and obtain the import_job_id.
When include_data=true, the 'data' result XML contains component-level detail for all import phases, including the DeleteComponents phase of an upgrade. Error code 0x8004F037 (image-column dependency failures) and other component-level errors from the deletion phase appear in this XML.
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnly, idempotent, non-destructive. Description adds behavioral details: mentions exclusion of large 'data' column by default, conditional retrieval via include_data, and specific error code 0x8004F037. No contradictions with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is concise (7 lines) and well-structured: first sentence states purpose, second lists return fields, third explains include_data, fourth links to sibling tools, fifth details error diagnostics. Every sentence adds value without 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 the tool's purpose (single record retrieval) and the presence of an output schema, the description covers all necessary aspects: return fields, optional data inclusion, error code clues, and preconditions. No gaps identified.
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 already provides detailed descriptions for all three parameters (dataverse_url, import_job_id, include_data). The tool description adds no new semantic information beyond what the schema contains. Baseline 3 is appropriate given high schema 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?
Clearly states 'Retrieve a single importjob record by its GUID to check import progress.' Distinguishes from sibling tools like dataverse_list_import_jobs (list) and dataverse_import_solution (start) by explicitly referencing them as prerequisites.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly advises when to use this tool (check import progress) and directs the user to dataverse_import_solution or dataverse_stage_and_upgrade_solution to obtain the import_job_id. Also describes include_data usage for failure diagnosis.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Answer "WHY did this solution import fail?" — the readable import results.
Calls the unbound RetrieveFormattedImportJobResults function, which returns the platform's own human-readable results document for one import job.
This is the companion to dataverse_get_import_job, which returns the importjob RECORD (progress, completedon, solutionname) and, with include_data=true, the raw 'data' column — a large opaque XML blob you then have to parse yourself to find the failure. This tool asks Dataverse to format those results instead. Use dataverse_list_import_jobs (most recent first) or the import_job_id returned by dataverse_import_solution / dataverse_stage_and_upgrade_solution to get an id.
RESPONSE SHAPE — LIVE-VERIFIED. The document arrives as ONE string property named FormattedResults, and the body carries nothing else. It is surfaced as 'results', with results_source naming the property it was read from. Nothing in the document is interpreted: the text is passed through verbatim. Microsoft Learn documents the function and its return type but NOT that type's inner properties, so the property is still located by name and then by shape rather than assumed; if the payload cannot be identified unambiguously, normalized is false, no length or summary is reported, and the payload comes back unchanged (minus the @odata.* envelope) under raw_response — read it yourself rather than trusting a guess.
WHAT YOU GET BACK IS A SPREADSHEET. Live-verified: 'results' is a SpreadsheetML (Excel XML) workbook — root element Workbook, an mso-application progid="Excel.Sheet" processing instruction and the urn:schemas-microsoft-com:office:spreadsheet namespace — NOT a Dataverse results schema. Its element names are spreadsheet furniture (Worksheet, Table, Row, Cell, Data, Style, Font, Interior, Border...) and NONE of them is named error, warning or failure. The meaning lives in the CELL VALUES, so to find out why an import failed you must read the TEXT of the document, not its tags. The same format came back for a completed job and a still-running one.
THE DOCUMENT IS TRIMMED BY DEFAULT, AND IT IS BIG. The function has no server-side paging — it returns the whole document in one string, and observed documents ran to tens of thousands of characters (about 14,000 for a small import, about 71,000 for a larger one), so the default WILL usually truncate. The first max_chars characters (default 20,000) are returned inline and the true size is never hidden: results_length is ALWAYS the full character count Dataverse returned and truncated says whether anything was cut. Raise max_chars (max 2,000,000) to read more; an import failure's reason is usually near the top, but spreadsheet markup is verbose, so budget generously.
A STRUCTURAL SUMMARY, NOT A VERDICT. When the document parses as XML, the summary reports root_tag, element_count, distinct_tag_count and element_counts (a per-tag tally) — computed over the WHOLE document, not just the returned slice, so it describes what you did not see as well as what you did. It is deliberately descriptive only: no node is labelled an error, a warning or a failure, because the document's schema is undocumented and a wrong "the import succeeded" verdict is worse than none. Given the SpreadsheetML format above, the tally counts spreadsheet structure and tells you little about the import itself — element_counts_note repeats that warning in the response. Read the text. If the document does not parse (it may be HTML or plain text), markup_parsed is false with a note explaining why and the text is still returned in full. Parsing uses a hardened parser that refuses XML entity declarations and external entity references outright.
Note the two ids are not interchangeable: this takes the importjob GUID (ImportJobId / importjobid), not the separate ImportJobKey string that ImportSolutionAsync also returns.
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only state readOnly/idempotent/destructive hints; the description adds crucial behaviors: the response is a single FormattedResults string, it is actually a SpreadsheetML workbook, trimming behavior with results_length and truncated, structural summary is not a verdict, and id distinction between ImportJobId and ImportJobKey. This far exceeds annotation baseline.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is far longer than typical, but it uses bold headings and short paragraphs to organize. However, it repeats the 'read the text' warning several times and contains ALL-CAPS phrases that could be trimmed without losing meaning, so it's not maximally 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?
Given the tool's complexity—unformatted vs formatted results, spreadsheet XML, truncation, summary semantics, and ID confusion—the description covers every failure mode an agent could encounter. It even explains what happens when the payload cannot be identified (raw_response fallback). The output schema exists, so return values need not be restated, and the description focuses on selection and invocation nuances.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With schema coverage reportedly 0%, the description compensates fully. It explains max_chars' default, maximum, and the fact that the full document may be truncated; it clarifies import_job_id is the GUID, not the ImportJobKey string; and it mentions dataverse_url requirement indirectly through the schema. The description adds operational meaning to every 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 opens with the user-facing question 'Answer "WHY did this solution import fail?"' then names the exact API function and contrasts with dataverse_get_import_job. This clearly specifies the verb (get formatted results), the resource (import job results), and differentiates it from sibling 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?
Explicitly names the companion tool dataverse_get_import_job and tells the agent when to use which ('returns the importjob RECORD ... raw data column'). Also provides how to obtain the id via dataverse_list_import_jobs or dataverse_import_solution / dataverse_stage_and_upgrade_solution.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fingerprint a Dataverse environment: server version, organization identity, endpoints.
Merges three unbound Web API functions — RetrieveVersion, RetrieveCurrentOrganization, and RetrieveOrganizationInfo. Call this before any risky operation to confirm which environment you are pointed at.
To tell a non-production environment from production, read organization_info.organizationInfo.InstanceType or current_organization.Detail.OrganizationType. Both are strings, and their values are distinct per tier — a developer-tier org reports "Developer", not "Sandbox" — so never test only for "Sandbox" when deciding whether an environment is safe to change. Identity lives alongside them: Detail.UniqueName, Detail.FriendlyName, Detail.EnvironmentId, Detail.Geo, and Detail.State.
RetrieveOrganizationInfo also returns every installed solution. That list runs to several hundred entries, so it is replaced by organization_info.organizationInfo.solutions_count. Set include_solutions=true to get the full Solutions array as well, but prefer dataverse_list_solutions for browsing solutions.
Each function is called independently. If one is unavailable or privilege-gated its failure is reported in partial_errors and the remaining data is still returned; only a failure of all three yields an error response. Apart from the solution summarization, payloads are returned as Dataverse produced them, minus the @odata envelope keys.
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare read-only, idempotent, and non-destructive behavior, so the description focuses on added context: each function is called independently, failures are collected in partial_errors, and only total failure yields an error response. It also discloses response shaping (@odata envelope removal) and performance-relevant solution summarization.
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 first sentence is a concise, front-loaded summary, and each following paragraph addresses a distinct, valuable concern: when to call, how to classify environments, solution handling, and partial-failure behavior. The length is justified by the tool's complexity, and no sentence is 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 description covers preconditions, environment-identity interpretation, output shaping, and partial-error semantics, which is complete for a tool that merges three Web API calls. An output schema is present, so the description does not need to enumerate every return field, but it still provides enough context to use the tool 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 schema itself documents dataverse_url, access_type, and include_solutions with clear descriptions. The tool description adds meaningful semantics for include_solutions—response-size impact, default behavior, and a preferred alternative tool. Access_type is not revisited in prose, but the schema already explains it thoroughly, so the gap is minor.
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 opens with 'Fingerprint a Dataverse environment: server version, organization identity, endpoints,' which names a specific verb, resource, and scope while distinguishing it from sibling lookup tools. It also differentiates the tool by naming the three merged Web API functions and the practical outputs it provides.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit usage guidance is provided: 'Call this before any risky operation to confirm which environment you are pointed at.' It also gives an explicit alternative for solutions browsing ('prefer dataverse_list_solutions') and warns against a common misclassification ('never test only for Sandbox').
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieve a single plug-in assembly record by its GUID.
The 'content' column contains the base64-encoded DLL and is very large — exclude it from select unless you specifically need it.
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and idempotentHint=true. The description adds valuable behavioral context by noting that the 'content' column is very large and should be excluded unless needed, which helps the agent avoid performance issues.
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: first states purpose, second provides a critical warning. No unnecessary words, front-loaded with essential information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple with one required parameter and an output schema. The description covers purpose and a key behavior, but omits parameter explanations for assembly_id and dataverse_url, reducing completeness. Adequate for the basic operation.
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 explain all parameters. It only addresses the 'select' parameter (via the content warning) but does not explain 'assembly_id' or 'dataverse_url', leaving them undocumented.
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 single plug-in assembly record by GUID, using specific verb and resource. It distinguishes from list siblings by emphasizing 'single' and 'by GUID', leaving no 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 provides usage advice by warning about the large 'content' column and recommending exclusion unless needed. However, it does not explicitly state when to use this tool versus alternatives like dataverse_list_plugin_assemblies, leaving the guidance implicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieve a single plug-in package record by its GUID.
Packages are an alternative to raw assemblies — Dataverse extracts the contained assemblies automatically on upload.
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already signal read-only, idempotent, and non-destructive behavior. The description adds context about packages being an alternative to assemblies and automatic extraction, which is useful but not critical. No contradictions with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences: first directly states the purpose, second adds relevant background. No wasted words, and the critical information is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of an output schema and comprehensive annotations, the description is nearly complete for a simple get-by-GUID operation. It could mention the return type or format, but overall sufficient.
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 provides full descriptions for all three parameters (select, package_id, dataverse_url), so description coverage is already high. The tool description adds no additional parameter information; baseline 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 verb 'retrieve' and resource 'single plug-in package record by its GUID'. It distinguishes from the sibling tool dataverse_list_plugin_packages which lists multiple records, and from other get tools by specifying the unique 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 is provided on when to use this tool versus alternatives (e.g., listing packages or getting other entities). Prerequisites, such as the need for a known GUID, are not mentioned, leaving the agent without decision support.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieve a single SDK message processing step record by its GUID.
Steps are the third node in the prerequisite chain: assembly → type → step → image.
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, destructiveHint. The description adds behavioral context by describing the prerequisite chain (assembly → type → step → image), which is useful for understanding operational constraints. It does not contradict annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: two sentences with a front-loaded purpose. The first sentence states the core function, and the second provides essential context (hierarchy). 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?
The tool has a clear purpose, annotations cover safety, output schema exists, and the description adds the hierarchical context. However, it could mention expected behavior when the GUID is not found (e.g., returns null or error) or any special handling. Still, given low complexity, it is fairly complete.
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 provides clear descriptions for each parameter (step_id, dataverse_url, select). The tool description does not add significant new meaning beyond the schema. Given that schema descriptions are comprehensive, the description adds minimal value for parameters.
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 'Retrieve', specifies the resource 'single SDK message processing step record', and identifies the identifier 'GUID'. It distinguishes from sibling tools like dataverse_list_plugin_steps by targeting a single record. The hierarchy note further clarifies the tool's place.
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 hierarchical context (assembly → type → step → image) implying that step requires prior assembly and type, but it does not explicitly state when to use this tool vs alternatives like dataverse_list_plugin_steps or other get_ tools. No when-not-to-use or alternative names are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieve a single plug-in step image record by its GUID.
Step images are pre/post entity snapshots passed to the plug-in context. They are the leaf node in the chain: assembly → type → step → image.
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, destructiveHint. Description adds hierarchical context but no additional behavioral traits like auth requirements, error cases, or pagination (not applicable). Value added is marginal.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences with clear structure: core action, definition, hierarchy. No redundancy, front-loaded with the main purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given moderate complexity, annotations present, and output schema exists, the description covers purpose and context but lacks parameter details (especially with 0% schema coverage). Adequate but incomplete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It only mentions 'by its GUID' implying image_id, but does not explain select or dataverse_url parameters. Adds little beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states it retrieves a single plug-in step image by GUID. Explains what step images are and places them in the hierarchy (assembly → type → step → image), distinguishing it from list and other get 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?
Implies usage via hierarchy context and 'by its GUID', but lacks explicit guidance on when to use this tool vs. alternatives like list_plugin_step_images. No when-not-to-use or prerequisites stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the current plug-in trace log setting for the Dataverse organization.
Returns the verbosity level: off (0), exception (1), or all (2).
This setting controls whether Dataverse records plug-in execution traces in the plugintracelog entity. Use dataverse_set_plugin_trace_log_setting to change the setting, and dataverse_list_plugin_trace_logs to read the logs.
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds value by detailing the return values (off, exception, all) beyond the annotations but does not cover all behavioral aspects (e.g., rate limiting).
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 efficient, with three concise sentences that front-load the purpose, then provide return details and sibling references. 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 simple nature of this read operation, the description is complete: it explains the purpose, return values, and relationship to sibling tools. The output schema likely covers return structure, so no additional explanation needed.
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?
Despite schema description coverage being 0% per context, the description does not add any semantics for the single parameter dataverse_url beyond what the schema already provides (which is a basic URL format). The description fails to compensate for the documented 0% 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 the tool gets the current plug-in trace log setting for the organization, using specific verbs and resource. It distinguishes from sibling tools by naming dataverse_set_plugin_trace_log_setting and dataverse_list_plugin_trace_logs.
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 explicitly tells when to use this tool (to get the setting) and mentions specific alternatives for changing or reading logs, providing excellent guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieve a single plug-in type record by its GUID.
Plug-in types represent individual .NET classes within an assembly. Use dataverse_list_plugin_types to browse types in a given assembly.
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=False, indicating a safe read operation. The description adds context about plug-in types being .NET classes but no further behavioral traits (e.g., permissions, rate limits, error handling). Since annotations cover the safety profile, the description is adequate but not enhanced.
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 exceptionally concise, consisting of three short sentences. It front-loads the core action, adds context, and then provides sibling guidance. Every sentence serves a clear purpose without redundancy or verbosity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple retrieval tool, the description covers the essential: what it retrieves, the key identifier, and a related sibling tool. Annotations provide safety and idempotency context. It does not mention return format or error handling, but the output schema likely covers that. Overall, it is sufficiently complete for its purpose.
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 description provides no information about parameters. Despite the input schema having detailed descriptions for 'dataverse_url', 'plugin_type_id', and 'select', the tool description does not explain their meaning or usage. With schema description coverage at 0%, the description fails to compensate, leaving the agent to rely solely on the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action: 'Retrieve a single plug-in type record by its GUID.' It specifies the resource (plug-in type record) and the key (GUID). It also distinguishes itself from the sibling 'dataverse_list_plugin_types' by explicitly directing users to that tool for browsing, making the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance: 'Use dataverse_list_plugin_types to browse types in a given assembly.' This advises when to choose the list tool over this get tool. Although it does not cover all possible alternatives or conditions, the guidance is clear and helpful for the primary use case.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieve a single Dataverse record by its GUID.
For multiple records with filtering use dataverse_query_table. Use dataverse_query_table first to find record IDs if you do not have one.
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false. The description does not contradict and is consistent. It adds no new behavioral info, but for a simple read tool the annotations suffice. No issues.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences that front-load the purpose and then provide crucial workflow guidance. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple record fetch tool with an output schema and rich annotations, the description covers the necessary workflow (when to use this vs query_table) and is complete. No 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 includes descriptions for each parameter, so schema coverage is high. The description does not add any extra meaning beyond what the schema already provides. Baseline 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 'Retrieve a single Dataverse record by its GUID.' It uses a specific verb and resource, and distinguishes from sibling dataverse_query_table for multiple records.
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 explicitly says 'Use dataverse_query_table first to find record IDs if you do not have one.' This provides clear when-to-use guidance and exactly when to use the sibling tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get full metadata for a single relationship by schema name — cascade configuration and navigation properties.
Schema names are case-sensitive; use the exact SchemaName from dataverse_list_relationships. Use this to fetch the full definition before updating with dataverse_update_relationship.
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate it is read-only, idempotent, and non-destructive. The description adds that it returns 'full metadata' including cascade configuration and navigation properties, and frames it as a precursor to updates, conveying additional 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 two concise sentences: the first states the purpose with key details, the second provides crucial usage guidance. Every word is necessary; no redundancy or fluff.
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, good annotations, and existing output schema, the description covers the core purpose and usage workflow. It could optionally mention the 'consistency_strong' parameter, but the schema handles that. Overall, it is sufficiently complete for a read operation.
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 description does not explicitly describe any parameters (0% coverage per context). However, the input schema provides detailed descriptions for each parameter, so agents can infer semantics from the schema. At baseline 3, the description adds no extra value but does not hinder understanding.
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 full metadata for a single relationship by schema name, specifying cascade configuration and navigation properties. It distinguishes itself from sibling tools like 'dataverse_list_relationships' by focusing on a single relationship and providing detailed definition.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states that schema names are case-sensitive and advises using the exact SchemaName from 'dataverse_list_relationships'. It also instructs to use this tool before updating with 'dataverse_update_relationship', providing clear when-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Answer "what can this security role actually DO?" — list a role's privileges.
Calls the unbound RetrieveRolePrivilegesRole function. This is the companion to dataverse_get_security_role, which returns the role RECORD (name, business unit, managed flag) and says nothing about what the role permits. Use dataverse_list_security_roles to find a role id by name.
Scope: this is the role's OWN privilege set. For a specific person's effective privileges across all their roles and teams use dataverse_retrieve_user_privileges, or dataverse_audit_user_access for the full access report.
RESPONSE SHAPE (verified live). Dataverse returns one top-level property, RolePrivileges, holding the whole list with no wrapper; privileges_source reports where the collection was found. Every entry carries all six of:
PrivilegeName — the familiar 'prvReadAccount' form. Already present on every entry, so NO extra lookup against the privileges table is made or needed.
PrivilegeId — GUID of the privilege.
Depth — the access level (see below).
BusinessUnitId — GUID of the business unit the depth is scoped to.
RecordFilterId, RecordFilterUniqueName — record-filter binding; empty on ordinary privileges.
Entries are passed through exactly as Dataverse sent them: nothing is added, renamed or dropped.
Depth arrives HUMAN-READABLE and is never relabelled. OData serializes the PrivilegeDepth enum as its member NAME, and only member names were observed live ("Basic", "Local", "Deep", "Global" — increasing scope, Global being org-wide; "Basic" is the user's own records). Should a numeric PrivilegeDepth code ever arrive instead, it is reported raw: that mapping is not confirmed for this function, and a wrong access-level label is more dangerous than an unlabelled one. depth_summary counts every entry by its Depth value.
THE LIST IS BIG AND IS TRIMMED BY DEFAULT. The function has no server-side paging — it returns every privilege in one response. Measured live: a System Administrator role carries 4,132 privileges in a ~1 MB raw response. That is why top defaults to 50 (~14 KB) and why the raw payload is never echoed back on the normalized path. The magnitude is never hidden: total_count is always the full number Dataverse returned regardless of trimming, has_more says whether anything was trimmed, and depth_summary is computed over ALL entries rather than just the returned page. Raise top (max 1000) to see more.
A well-formed but nonexistent role id returns an ERROR, not an empty list: Dataverse answers HTTP 404 [0x80040217] "Entity 'role' With Id = ... Does Not Exist", surfaced through the standard {"error": true, "message": ...} envelope. An empty privileges list therefore means a real role that grants nothing.
The function's inner properties are undocumented on Microsoft Learn, so the collection is still located by shape as well as by name (RolePrivileges first, then a lone object-list at the top level, then one level down inside a named wrapper) as insurance against a future platform change. If it cannot be identified unambiguously, nothing is guessed: normalized is false, no counts are reported, and the payload comes back unchanged under raw_response (minus the @odata.* envelope) for you to read yourself.
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark this read-only and non-destructive, so the bar is lower, but the description goes far beyond: it discloses the lack of server-side paging, default trimming with total_count/has_more/depth_summary, the exact response shape, how Depth values arrive, and the raw_response fallback. No contradiction with the annotations exists.
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 long but well-structured with clear headings and bullets, and it front-loads the purpose. Every behavioral section earns its place, though some of the trimming rationale repeats the input schema's top description verbatim, making it slightly less concise than it could be.
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, the description is remarkably complete: it covers purpose, alternatives, response shape, field semantics, trimming behavior, error handling, and fallback behavior. An agent has enough context to invoke the tool correctly and interpret its results, even without the output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides detailed descriptions for role_id, top, and dataverse_url, including defaults, max, and the trimming rationale. The description reinforces and contextualizes these parameters but does not add substantial parameter-level meaning beyond what the schema already says, so it stays at the baseline for high schema 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 opens with a concrete question and states it lists a role's privileges—clearly naming the verb and resource. It explicitly distinguishes itself from dataverse_get_security_role (which returns the role record) and other sibling tools, so an agent can tell exactly what this tool produces.
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 gives explicit when-to-use guidance and names alternatives: use dataverse_list_security_roles to find a role id, and use dataverse_retrieve_user_privileges or dataverse_audit_user_access for a user's effective privileges. It also clarifies edge-case behavior (404 for nonexistent role, empty list meaning a real role with no privileges), which is exceptionally helpful for correct tool selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Resolve an SDK message (e.g. 'Create', 'Update', 'Delete') to its sdkmessageid.
Call this to get the message_id required by dataverse_create_plugin_step. Provide message_name OR message_id — exactly one required.
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, indicating safe read-only behavior. The description adds valuable context about the exact mapping (name to ID) and its role in plugin step creation, going beyond what annotations provide. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences plus a concise requirement line. It immediately states the core function and use case, with no fluff. Every sentence serves a purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (a lookup with two optional parameters) and the presence of an output schema (mentioned), the description covers the essential purpose, input constraints, and usage context. It is complete for an agent to select and invoke 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?
Although the input schema provides descriptions for each parameter (100% coverage by default), the description adds a crucial constraint: 'Provide message_name OR message_id — exactly one required.' This clarifies the mutual exclusivity, which is not enforced by the schema (both are optional individually). Thus it adds meaningful 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 verb 'resolve', the resource 'SDK message', and the specific output 'sdkmessageid'. It also mentions the downstream use case (required by dataverse_create_plugin_step), distinguishing it from sibling tools like dataverse_list_sdk_messages.
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 explicitly says 'Call this to get the message_id required by dataverse_create_plugin_step' and specifies 'Provide message_name OR message_id — exactly one required.' This gives clear context for when to use. It could benefit from stating when not to use, but it is already effective.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Resolve the filter that scopes an SDK message to one entity — returns the sdkmessagefilterid.
Call this to get the filter_id required by dataverse_create_plugin_step when you want to scope a step to a specific entity (e.g. 'contact'). Provide filter_id alone, or message_id + primary_entity together.
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is fully covered. The description adds that it returns the sdkmessagefilterid but does not disclose error conditions or rate limits, which is acceptable given the annotation coverage.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences long, front-loaded with the core purpose, and every sentence earns its place. No redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple lookup tool with robust annotations and an output schema, the description adequately explains the two usage modes and the return value. It is sufficiently complete for an agent to determine when and how to invoke the tool 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 provides detailed descriptions for all parameters (100% coverage), so the baseline is 3. The description paraphrases the schema (e.g., 'Provide filter_id alone, or message_id + primary_entity together') but does not add new semantic information beyond what is already in 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?
Description clearly states it resolves an SDK message filter to return the sdkmessagefilterid, with explicit mention of its use in dataverse_create_plugin_step. It distinguishes itself from siblings like dataverse_list_sdk_message_filters by focusing on resolving a single filter ID via two modes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Description provides specific usage context (for scoping plugin steps) and explains the two parameter modes (filter_id alone or message_id+primary_entity). While it doesn't explicitly mention when not to use it, the guidance is clear and actionable for an AI agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieve a single Dataverse security role by its GUID.
Returns full role details including name, business unit, and managed status.
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint, idempotentHint, and destructiveHint. The description adds useful context about returned fields (name, business unit, managed status) without contradicting annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the core action and resource, no redundant words. Every sentence 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?
Sufficient for a simple retrieval tool with good annotations and output schema. Could mention error handling or missing GUID, but not critical.
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 already provides descriptions for each parameter, so the tool description does not add additional meaning. Baseline of 3 is appropriate given schema 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 the action 'Retrieve' and the resource 'a single Dataverse security role by its GUID', distinguishing it from sibling tools like dataverse_list_security_roles.
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 context of sibling names implies it's for single role retrieval, but no when-not or exclusion criteria are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read one setting's FINAL COMPUTED value for this environment.
Calls the unbound RetrieveSetting function, which returns the value actually in effect after the platform has applied its precedence rules, rather than a raw configuration row that only tells you what someone stored at one level. That makes it the tool for diffing configuration between environments: compare computed values, not rows.
It reads a NAMED setting from the settings framework, addressed by its unique name. It is not a general reader for the organization row: a column such as plugintracelogsetting is not a setting name, and dataverse_get_plugin_trace_log_setting (or dataverse_query_table over organizations) is what reads those.
Omit app_unique_name to read the ORGANIZATION-level value. Supply the unique name of a model-driven app to read the value as that app sees it, which can differ where an app-level override exists. The two are different requests: when app_unique_name is omitted the parameter is left out of the call entirely rather than sent empty.
THE VALUE IS NESTED. Microsoft Learn documents RetrieveSettingResponse but not its inner properties; live, v9.2 answers {"SettingDetail": {"Name": ..., "Value": "false", "DataType": 2}}. setting_value is lifted out of that container and setting_value_source says where it came from (normally SettingDetail.Value). setting_detail_name and setting_data_type carry its siblings; DataType is an INTEGER CODE passed through unmapped, since no verified code-to-type-name table exists. Note Value is a STRING — "false", not a JSON boolean — so parse it yourself rather than testing truthiness.
AN UNKNOWN SETTING NAME IS NOT AN ERROR. Dataverse answers HTTP 200 with SettingDetail: null. That is reported as setting_found: false with no setting_value, and it is a DIFFERENT answer from a setting that exists and holds "", "false" or 0 — those come back as setting_found: true with the value. Never read a missing setting_value as "the setting is off".
If the payload matches neither shape, setting_value is OMITTED rather than guessed and normalized is false. raw_response (minus the @odata.* envelope) always rides along on every path, so the extraction can be checked.
Setting names come from the settingdefinitions table (112 rows on a stock org), which dataverse_query_table can list. Both URL forms are live-verified to return HTTP 200: SettingName alone, and SettingName with AppUniqueName.
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark this as readonly/idempotent, but the description goes far beyond that: it reveals the nested response shape, the unknown-setting-name HTTP 200 behavior (setting_found: false), the STRING vs boolean caveat, DataType unmapped integer code, and raw_response always included. This is exemplary behavioral disclosure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long but well-structured into focused paragraphs. Every section adds necessary nuance (precedence, app overrides, nested value, unknown-name behavior, fallback). It could shave some redundancy with the schema's app_unique_name description, but the extra context about request-level differences 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 complexity and the presence of an output schema, the description covers all critical edge cases: missing settings, value types, data source, raw response, and the semantics of the two request forms. It also tells the user how to discover valid setting names. It is complete enough to invoke correctly and interpret results.
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?
Despite the schema having per-parameter descriptions, the context signal says schema description coverage is 0%, so the tool description must compensate. It richly explains setting_name (from settingdefinitions, not display label) and app_unique_name (omit vs empty leads to different calls). However, it doesn't mention dataverse_url at all, leaving that param's semantics entirely to the schema, so a perfect score isn't warranted.
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 opens with a specific verb+resource: 'Read one setting's FINAL COMPUTED value for this environment.' It clearly distinguishes this from raw configuration reads and from organization-row readers like dataverse_get_plugin_trace_log_setting, making the tool's niche unmistakable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use: diffing configuration between environments by computed values. It also provides clear exclusions: not a general organization row reader, and names alternatives (dataverse_get_plugin_trace_log_setting, dataverse_query_table). The app_unique_name omission vs. empty distinction is also a usage guideline.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieve a single Dataverse solution by its unique name or GUID.
Returns full details including version, publisher, and managed status. Provide solution_unique_name or solution_id — not both.
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Adds context beyond annotations by specifying 'Returns full details including version, publisher, and managed status'. No contradiction with readOnlyHint or other annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three succinct sentences: purpose, return details, parameter constraint. 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?
With output schema present, description suffices by stating key return fields and parameter requirements. No critical 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 already describes each parameter (coverage 100% in actual schema, though context says 0% likely incorrect). The description adds the constraint 'not both', which clarifies usage beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states 'Retrieve a single Dataverse solution by its unique name or GUID', specifying verb and resource. Distinguishes from sibling tools like dataverse_list_solutions and dataverse_export_solution.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides the essential constraint 'Provide solution_unique_name or solution_id — not both' but lacks explicit guidance on when to use this tool over siblings that list or export solutions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieve a single solution history record by its GUID.
Returns import/upgrade/export operation details including result, timing, error messages, and publisher information from msdyn_solutionhistories.
The msdyn_suboperation field distinguishes operation sub-types:
3: Import/Update (in-place overlay; obsolete components are NOT deleted)
5: Upgrade-with-deletion (DeleteComponents phase; obsolete components ARE deleted)
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, but the description adds value by detailing returned information (result, timing, error messages, publisher info) and explaining the msdyn_suboperation field (3 vs 5). This provides behavioral context beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, with two short paragraphs. The first sentence delivers the purpose, the second lists return contents, and the final paragraph explains a key field. No extraneous information is 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 presence of an output schema (not fully shown), the description covers the essential return details and provides a useful explanation of the suboperation field. However, it omits guidance on when to use the select parameter or how this tool relates to the sibling list tool, which would enhance completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides comprehensive descriptions for all parameters (dataverse_url, solution_history_id, select). The tool description does not add significant new parameter semantics beyond stating that the ID is a GUID. With high schema coverage, a baseline of 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 'Retrieve a single solution history record by its GUID,' specifying the exact verb and resource. It distinguishes from the sibling 'list_solution_histories' tool by focusing on a single record retrieval.
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 explicitly state when to use this tool versus alternatives like list_solution_histories. It implies usage when a specific GUID is known, but lacks explicit guidance or context for selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get schema details for a single Dataverse table by logical name.
Returns the entity set name, primary key attribute, and primary name attribute. Use dataverse_list_tables to discover available table logical names.
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds behavioral context beyond annotations: it specifies the returned attributes and explains the consistency_strong parameter's caching behavior and performance implications. This aligns with readOnlyHint, idempotentHint, and destructiveHint annotations without contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with four sentences, front-loaded with purpose. Every sentence adds value, including return values and prerequisite guidance. 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 output schema exists (implied by context), the description adequately covers the tool's purpose, return values, and parameter behavior. It is complete for a read-only metadata retrieval 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 fully describes all three parameters (table_name, dataverse_url, consistency_strong) with individual descriptions. The tool description does not add parameter-level meaning beyond the schema, so baseline score of 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 the tool retrieves schema details for a single Dataverse table by logical name, specifying the return values (entity set name, primary key, primary name attribute). This distinguishes it from sibling tools like dataverse_list_tables which list available tables.
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 instructs users to use dataverse_list_tables to discover table logical names, providing a clear prerequisite. However, it lacks explicit guidance on when not to use this tool or direct comparison with other get_* tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieve a single Dataverse team by its GUID.
Returns full team details including name, type, and business unit.
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, destructiveHint. The description adds return details (name, type, business unit) but does not disclose additional behaviors like permissions or rate limits. No 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?
Two sentences, no fluff. Front-loaded with the core action. Every word adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Adequately covers purpose and return values. Lacks mention of error handling, required permissions, or validation of GUID format. 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 descriptions are comprehensive for all parameters (team_id, dataverse_url, select). The tool description does not add parameter meaning beyond that. Baseline score applies due to high schema 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 the verb 'Retrieve' and resource 'single Dataverse team' with identifier 'GUID'. It distinguishes from sibling tools like dataverse_get_user by specifying 'team'. No ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives (e.g., dataverse_list_teams) or when not to use it. The description only states the function, lacking context for selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Answer "what can this TEAM actually DO?" — list a team's privileges.
Calls the entity-bound RetrieveTeamPrivileges function on the team record. It takes no parameters of its own: the team id is the key predicate.
This completes the three-way security picture. dataverse_get_role_privileges answers it for a ROLE, dataverse_retrieve_user_privileges for a USER, and this for a TEAM — the missing third. It is the companion to dataverse_get_team, which returns the team RECORD (name, type, business unit) and says nothing about what the team permits. Use dataverse_list_teams to find a team id by name, and dataverse_audit_user_access for one person's full access report across their direct roles and team memberships.
RESPONSE SHAPE. Microsoft Learn documents the call and the return type RetrieveTeamPrivilegesResponse but NOT its inner properties. VERIFIED LIVE: the collection arrives under RolePrivileges — NOT TeamPrivileges, despite the response type name — exactly as the sibling RetrieveUserPrivileges does. The collection is still located by name first (TeamPrivileges, which has never been observed, then RolePrivileges, which is what really comes back) and then by shape: a lone object-list at the top level, then one level down inside a named wrapper. privileges_source reports where it was found, so check it. If no collection can be identified unambiguously, nothing is guessed: normalized is false, no counts are reported, and the payload comes back unchanged under raw_response (minus the @odata.* envelope) for you to read yourself.
AN EMPTY LIST IS A REAL ANSWER, NOT A FAILURE. count: 0 with normalized: true means the team has NO DIRECTLY-ASSIGNED SECURITY ROLES — a common and entirely normal state, and the usual one: most teams get their access from their members' own roles rather than from a role assigned to the team itself. Do not read it as an error, and do not read it as "this team's members have no access": members still hold their own roles, and dataverse_audit_user_access is the tool for a person's effective access.
Entries mirror RetrieveRolePrivilegesRole's, VERIFIED LIVE for teams across 484 entries: PrivilegeName ('prvReadAccount'), PrivilegeId, Depth, BusinessUnitId, RecordFilterId, RecordFilterUniqueName — one identical key set on every entry, with PrivilegeName present and populated throughout, so no name-resolution step is needed. Entries are passed through EXACTLY as Dataverse sent them — nothing is added, renamed or dropped — so trust the returned keys over this list.
Depth is never relabelled. OData serializes the PrivilegeDepth enum as its member NAME, and this function was VERIFIED LIVE to return the member name — "Basic", "Local", "Deep", "Global" (increasing scope, Global being org-wide) — as a STRING on every one of 484 entries, with no numeric PrivilegeDepth code ever arriving. Should one nonetheless arrive it is reported raw rather than mapped: a wrong access-level label is more dangerous than an unlabelled one. depth_summary counts every entry by its Depth value, over the WHOLE list before any trimming.
This function and dataverse_get_role_privileges return the SAME privilege set for a team and its assigned role, but in a DIFFERENT ORDER — verified live as equal sets, unequal sequences. Never assume the two line up by index.
THE LIST CAN BE BIG AND IS TRIMMED BY DEFAULT. The function has no server-side paging — it returns every privilege in one response — and a team carrying a broad role inherits thousands of privileges (the role function was measured live at 4,132 privileges in a ~1 MB response). top therefore defaults to 50. The magnitude is never hidden: total_count is always the full number Dataverse returned, has_more says whether anything was trimmed, and depth_summary is computed over ALL entries rather than the returned page. Raise top (max 1000) to see more.
A well-formed but nonexistent team id returns an ERROR, not an empty list — VERIFIED LIVE: Dataverse answers HTTP 404 [0x80040217] "Does Not Exist", as the role function does, and it is surfaced through the standard {"error": true, "message": ...} envelope. The two cases are therefore distinguishable: an empty privileges list is always a REAL team with no directly-assigned roles, never a bad team id.
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, but the description adds substantial behavioral detail beyond those flags: live-verified response shape (RolePrivileges vs TeamPrivileges), no server-side paging with trimming behavior, total_count/has_more semantics, Depth value mapping, error handling for nonexistent team ids, and the meaning of an empty list with normalized: true. No contradictions with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long but well-structured with bolded section headers (RESPONSE SHAPE, AN EMPTY LIST IS A REAL ANSWER, THE LIST CAN BE BIG, etc.) and front-loads the core purpose. Every section covers a distinct, operationally important aspect. It could be tightened by reducing repeated 'VERIFIED LIVE' phrasing, but overall each sentence 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 complexity, the description is extremely complete: it explains the response collection naming quirk, entry key set, Depth representation, trimming with total_count/has_more, error vs empty-list distinction, and relationships to sibling tools. Even though an output schema exists, the description adds crucial live-verified details that the schema cannot convey, making it fully adequate for an agent to select and invoke 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 schema already provides descriptions for team_id, top, and dataverse_url, so the description does not need to repeat them. It adds significant extra meaning for top (why it defaults to 50, max 1000, total_count/has_more, depth_summary computed over all entries) and for team_id (finding via dataverse_list_teams, the key predicate). It does not explicitly discuss dataverse_url, but that parameter is self-explanatory and well-covered by 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 opens with a specific verb+resource+scope: 'Answer what can this TEAM actually DO? — list a team's privileges.' It clearly distinguishes from siblings by naming dataverse_get_role_privileges, dataverse_retrieve_user_privileges, and dataverse_get_team, positioning itself as 'the missing third' and the companion that returns permissions rather than the team record.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit guidance appears throughout: use dataverse_list_teams to find a team id by name, dataverse_get_team for the team record, dataverse_audit_user_access for one person's effective access, and dataverse_get_role_privileges when comparing to a role's privileges. It also clarifies that an empty list is a normal answer, not a failure, and warns not to interpret team members' access from this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get approximate row counts for many Dataverse tables in one round trip.
Calls the unbound RetrieveTotalRecordCount function with up to 50 table logical names (singular and lowercase — 'account', not 'accounts') and returns a {logical_name: count} map.
The counts come from a snapshot Dataverse takes at most once every 24 hours, so they are approximate and can lag reality by up to a day: a table populated an hour ago may report 0, and recent deletions may still be included. Worse, on an environment where the snapshot job has not run, EVERY count comes back 0 while the tables actually hold data (observed live on an org whose real counts were in the hundreds). The response flags that case with all_counts_zero=true — read it as "unknown", not "empty". Use this tool for cheap bulk sizing (which tables hold data, rough magnitudes, migration planning), and dataverse_count_records whenever an exact, live, or filtered count matters.
Unknown names are all-or-nothing, NOT silently dropped: a single logical name Dataverse does not recognize fails the whole call with HTTP 400 ([0x80040203] "Entity X was not found in the CRM system") and no partial results come back. Pass names you have already confirmed exist — dataverse_list_tables is the cheap way to confirm them. The error message names the offending table so you can drop it and retry.
If the response is not in the expected shape it is returned unchanged under raw_response with normalized=false rather than being guessed at.
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations (readOnlyHint, openWorldHint, etc.), the description reveals critical behavioral nuances: counts are stale by up to 24 hours, all_counts_zero=true means 'unknown' not 'empty', unrecognized names fail the entire call with HTTP 400, and raw_response fallback for unexpected shapes. This is far beyond what annotations convey.
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 front-loaded with the core purpose, then logically organized into paragraphs covering approximation caveats, all-zero edge case, failure behavior, and response fallback. Each sentence contributes specific, non-redundant information, making the length appropriate 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 complexity, existing output schema, and annotations, the description leaves no meaningful gaps: it covers freshness, false-zero indication, error semantics, name validation, and response normalization. It is fully self-sufficient for an agent to select and invoke 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?
Despite the context signal of 0% schema description coverage, the description thoroughly explains the entity_names parameter: singular and lowercase logical names, not plural OData set names; the 1-50 array limit and URL length reasoning; name grammar requirements; and that any unrecognized name aborts the call. It also notes splitting for long names, fully compensating for any schema gaps.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb-resource-scope statement: 'Get approximate row counts for many Dataverse tables in one round trip.' It clearly distinguishes itself from sibling dataverse_count_records by emphasizing the bulk, approximate nature and the map return format.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit guidance is provided: 'Use this tool for cheap bulk sizing... and dataverse_count_records whenever an exact, live, or filtered count matters.' It also recommends dataverse_list_tables for confirming entity names before invoking this tool, giving both positive and alternative usage contexts.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieve a single Dataverse system user by their GUID.
Returns full user details including fullname, domainname, email, and disabled status. Use dataverse_whoami to get the current caller's UserId.
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate read-only, idempotent, non-destructive. Description adds value by specifying return fields and the need for GUID, with no contradictions.
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 efficient sentences: first states purpose, second covers return details and a usage hint. No fluff.
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?
Covers purpose, inputs, and output fields sufficiently for a simple get tool, given that output schema exists. Could mention error handling or not found scenarios.
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?
Input schema has detailed parameter descriptions (100% coverage), so baseline is 3. Description adds marginal value by linking user_id to whoami but doesn't explain select or dataverse_url beyond 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?
Clear verb (retrieve), specific resource (Dataverse system user), and identifier method (GUID). Distinguishes from siblings by mentioning dataverse_whoami for caller's UserId.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides one explicit alternative (whoami) but does not comprehensively compare to other sibling get tools like dataverse_get_record or list variants.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List WHICH tables may take part in a relationship — the enumeration, before you pick a target.
Answers "which tables are eligible?" when you do not yet know what to point a lookup at. Its counterpart dataverse_check_relationship_eligibility answers "is THIS ONE table OK?" — a boolean about a table you can already name. The role values here mirror that tool's check_type values one for one, so use this to discover a candidate and that one to confirm a specific choice.
Call it before dataverse_create_one_to_many_relationship or dataverse_create_many_to_many_relationship: a table the platform excludes (many system and virtual tables) fails the create late and opaquely.
role selects one of three unbound functions:
'referenced' — tables that can be the PRIMARY (one) side of a 1:N, i.e. valid lookup TARGETS.
'referencing' — tables that can be the RELATED (many) side of a 1:N, i.e. tables that can HOLD a lookup.
'many_to_many' — tables that can participate in an N:N. Takes no table_logical_name; supplying one is an input error rather than being ignored, because ignoring it would answer the environment-wide question while looking scoped.
table_logical_name DOES NOT NARROW THE ANSWER. It is optional for the two 1:N roles and Dataverse does validate it server-side (an unknown table is HTTP 400 [0x80041102] "not found in the MetadataCache"), but supplying it was measured live to return a BYTE-IDENTICAL list to omitting it, for every table tried. Every role therefore answers the environment-wide question: the tables eligible for that role at all. Passing a name buys you exactly one thing — proof the table exists — so pass it only when you want that check, and never read the result as "the tables THIS table may point at". This holds for CUSTOM tables as well as system ones: scoping by a custom table returned the same byte-identical 575-name list that 'account' and 'systemuser' did. The response says so explicitly via table_logical_name_filtered.
To ask about one specific table, use dataverse_check_relationship_eligibility, which returns a real per-table boolean. This tool cannot answer that question.
Supply a lowercase logical name ('account', not 'accounts'). Omitting it removes the parameter from the call entirely rather than sending an empty one — the two are different requests, even though they answer the same.
THE ANSWER IS BIG and 'referenced' is the biggest. Measured live: referenced 575 names / ~13 KB, many_to_many 305 / ~7 KB, referencing 166 / ~4 KB. None of these functions pages server-side, so names are trimmed to top (default 250) while count, total_count and has_more always describe the full set Dataverse returned.
The list is returned under EntityNames (live-confirmed for all three functions), which is tried first, then a by-shape fallback (a sole top-level list of strings); source names where it was actually found. If it cannot be located unambiguously, table_logical_names and the counts are OMITTED, normalized is false, and the untouched body is returned under raw_response — an unreadable payload is never reported as an empty list.
An empty list from a readable payload IS a real answer: it means no table qualifies for that role. A nonexistent table name is an HTTP error, not an empty list.
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations (readOnlyHint, idempotentHint, destructiveHint), the description discloses highly relevant behavioral quirks: no server-side paging, client-side trimming, byte-identical lists when table_logical_name is supplied, fallback parsing logic, and the meaning of empty lists. It also discloses measured live sizes and error behavior (HTTP 400 for unknown names). These are exactly the kind of details that save an agent from misinterpreting results.
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 front-loaded with the core purpose and sibling distinction, and every paragraph adds essential caveats. However, it is quite long and repeats certain points (e.g., 'byte-identical' appears multiple times, 'measured live' is used repeatedly). Some trimming could be done without losing value, but overall the structure is logical and the detail is mostly earned.
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 and annotations cover safety, the description still goes beyond to explain response shape, fallback mechanism, raw_response behavior, and empty-list semantics. It covers the full context an agent needs to correctly invoke this tool and interpret results, including warnings about huge payloads and the exact behavior of the optional table_logical_name parameter. This is complete for the tool's complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Although the input schema already has descriptions for each parameter, the tool description adds critical semantic nuance beyond the schema. For role, it clarifies that every role answers the environment-wide question and gives exact meanings for 'referenced', 'referencing', and 'many_to_many'. For table_logical_name, it emphasizes that the parameter 'DOES NOT NARROW THE ANSWER' and that omission is different from sending an empty string. It also explains top's trimming behavior with concrete numbers.
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 opens with a specific verb and resource: 'List WHICH tables may take part in a relationship — the enumeration, before you pick a target.' It immediately distinguishes itself from the sibling tool dataverse_check_relationship_eligibility by contrasting 'which tables are eligible?' with 'is THIS ONE table OK?'. This is a clear, actions-focused purpose statement that leaves no 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 provides explicit when-to-use guidance: 'Call it before dataverse_create_one_to_many_relationship or dataverse_create_many_to_many_relationship' and directs users to the alternative tool for single-table checks: 'To ask about one specific table, use dataverse_check_relationship_eligibility'. It also explains that table_logical_name should only be passed to prove existence, and that the tool is meant for the 'do not yet know what to point a lookup at' scenario.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a single Dataverse view's layout as structured JSON.
Parses FetchXml and LayoutXml into readable columns, sort, and filter lists. Returns fetchxml_backup and layoutxml_backup for reference. quick_find_fields is populated for Quick Find views (querytype=4). Use dataverse_list_views to discover view IDs.
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Description complements annotations (readOnlyHint, idempotentHint) by detailing output structure: parsing FetchXml/LayoutXml, backup fields, and special handling for Quick Find views. No contradictions with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Five concise sentences, each adding unique information: purpose, parsing details, backup fields, Quick Find behavior, and sibling tool reference. No redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Description covers purpose, usage, output specifics, and prerequisite. For a read-only tool with output schema, no critical gaps remain.
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 descriptions already clearly define view_id and dataverse_url parameters. Description does not add additional semantic meaning or constraints beyond what 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?
Description clearly states it retrieves a single Dataverse view's layout as structured JSON, with specific verb 'Get' and resource 'view'. It differentiates from sibling dataverse_list_views by explicitly advising to use that tool for discovery.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly advises using dataverse_list_views to discover view IDs, providing a clear prerequisite. Describes output features (columns, sort, filters, quick_find_fields) but lacks explicit when-not-to-use guidance for other scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieve a single webresource record by its GUID.
Returns webresourceid, name, displayname, webresourcetype (+ label), description, languagecode, ismanaged, iscustomizable, createdon, modifiedon. Set include_content=true to also retrieve the base64-encoded content field (may be large for images and script bundles — a 5 MB cap applies).
IMPORTANT: this returns the PUBLISHED version of the web resource. Edits made via dataverse_update_web_resource are saved to the unpublished draft and will NOT appear here until you call dataverse_publish_customizations for this web resource. (Use dataverse_retrieve_unpublished with entity_set_name='webresourceset' to read the draft before publishing.)
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations (readOnly, idempotent, non-destructive), the description discloses the published-versus-draft behavior, which is a critical non-obvious trait. It also notes the 5 MB content cap, adding safety and expectation management. No contradictions with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is appropriately sized for the tool's complexity: a clear first sentence, a compact list of returned fields, and a short parameter note. The IMPORTANT caveat is set off in a new paragraph, front-loading the most critical behavioral note. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers return fields, parameter guidance, the published/draft distinction, and the content size cap. The output schema handles return typing, so the description's focus on semantics and caveats makes it complete for an agent to select and invoke 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 description adds meaning to include_content beyond the schema: it explains the base64 encoding, potential size for images/script bundles, and the 5 MB cap. The other parameters (URL and GUID) are self-explanatory in the schema, and the description's guidance on when to set include_content covers the one non-trivial 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 opens with a specific verb+resource: 'Retrieve a single webresource record by its GUID.' It clearly identifies the resource type and the key identifier, distinguishing it from list operations and the unpublished retrieval tool. The list of returned fields further scopes the operation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly contrasts with dataverse_update_web_resource and dataverse_retrieve_unpublished: states that edits are not visible in published retrieval until publish_customizations is called, and points to dataverse_retrieve_unpublished for draft reads. Also advises on the include_content parameter with a size caution, giving clear when-to-use context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Check whether a solution component can be customized BEFORE trying to edit it.
Calls the unbound IsComponentCustomizable function. Nothing is read or modified — it is a cheap pre-flight check for the metadata write tools (dataverse_update_table, dataverse_update_column, dataverse_update_relationship, dataverse_update_choice, dataverse_delete_column, ...), which otherwise fail late and opaquely when the target belongs to a managed solution that locked it down. Run this first when editing anything you did not create yourself.
Pass the component's own GUID (a table's or column's MetadataId, a form's or web resource's record id — NOT a solution id) plus the integer component_type code that says what the GUID refers to. The codes are the same set dataverse_analyze_dependencies uses (1=Entity, 2=Attribute, 3=Relationship, 9=OptionSet, 60=SystemForm, 61=WebResource, 300=CanvasApp, ...); the resolved name is echoed back as component_type_name so a mismatched code is easy to spot.
The verdict is returned as a top-level is_customizable boolean. Dataverse's response was verified live and is flat, carrying exactly one property named after the function itself — {"IsComponentCustomizable": true} — which is read directly; is_customizable_source names the property the value came from. If a future platform version answers in some other shape, a lone boolean anywhere in the payload is still accepted as a fallback, and when no verdict can be identified unambiguously the key is OMITTED rather than guessed or returned as null, with normalized false and a message saying so. Never read a missing is_customizable as false. The payload is always echoed unchanged under raw_response (minus the @odata.* envelope).
A false answer means the component belongs to a managed solution whose publisher locked it down. A true answer is not a guarantee that every edit will succeed: individual managed properties (for example IsRenameable or IsValidForAdvancedFind) can still block a specific change on an otherwise customizable component.
DO NOT ASSUME SYSTEM COMPONENTS ANSWER false. Core out-of-the-box tables report true (systemuser, component type 1, was verified as true) because the platform permits customizations such as adding columns even though the base asset itself is managed. The tool does discriminate — a managed web resource (type 61) returned false while an unmanaged one returned true.
A well-formed GUID that matches no component is an HTTP 400 carrying [0x80040216] "There should be at least one metadata entity returned for EntityName: ...", surfaced through the standard {"error": true, "message": ...} envelope: it means the component id (or the component_type paired with it) is wrong, not that the component is locked.
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations provide readOnlyHint=true, idempotentHint=true, destructiveHint=false, so safety context is already clear. The description adds substantial behavioral context beyond that: the exact response shape (flat payload, single property named after the function), fallback behavior when future formats change, omission rather than null when no verdict is found, echoing raw_response, and HTTP 400 error behavior for mismatched GUIDs. The warning against reading missing is_customizable as false and the customizability nuance (managed properties can block specific edits even when the verdict is true) are valuable operational caveats the annotations could not convey.
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 long but every paragraph earns its place: opening recommendation, function call specifics, response format, false/true semantics, the non-obvious system component behavior, and error identification. The first sentence is a clear front-loaded purpose statement. Paragraphs are short with bolded key phrases (BEFORE, DO NOT ASSUME, is_customizable) that aid scanning. The only minor redundancy is the sentence about component_type codes being echoed back as component_type_name, but it directly supports the 'mismatched code easy to spot' point, so no waste. This is efficient density, not padding.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only pre-flight check with an output schema present, the description is complete. It covers what the tool does, when to use it, how to interpret both true and false verdicts, the exact payload shape, error behavior, and even addresses a common wrong assumption (system components). The presence of an output schema means return-value documentation isn't the description's job, and the description deliberately does not over-explain the output. The combination of annotations, rich schema param descriptions, and this behavioral narrative leaves no practical questions unanswered.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema parameters already have strong descriptions (component_id explains NOT a solution id and includes concrete examples; component_type lists common values and links to Microsoft docs). The description adds crucial guidance beyond the schema: the component_type codes are the same set dataverse_analyze_dependencies uses, the resolved name is echoed back to catch mismatches, and the error semantics when component_id doesn't match a component. Given schema coverage is 0% in the structured sense but the description and schema complement each other well, and the description adds meaningful interpretive context, this earns a 4.
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 opens with a specific verb and resource: 'Check whether a solution component can be customized BEFORE trying to edit it.' It clearly distinguishes this pre-flight check tool from sibling update/delete tools and from read-only introspection tools like dataverse_analyze_dependencies (which shares the component_type code set). The resource (solution component) and the scope (customizability pre-check) are explicit and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use: 'Run this first when editing anything you did not create yourself' and lists the exact write tools that benefit (dataverse_update_table, dataverse_update_column, etc.). It also gives behavioral guidance about interpreting results: a false answer means managed solution lock, while true is not a guarantee because managed properties can still block edits. It even warns not to assume system components answer false and provides example verified results. This is textbook when-to-use-this-vs-alternatives guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List alternate keys (EntityKeyMetadata) defined on a Dataverse table.
Alternate keys let integration tools upsert records by business values instead of GUIDs. Returns SchemaName, LogicalName, KeyAttributes, and EntityKeyIndexStatus (which tracks async index build progress). Use the LogicalName with dataverse_delete_alternate_key to remove a key.
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate this is read-only, open-world, idempotent, and non-destructive. The description adds valuable behavioral detail beyond annotations: it lists the specific fields returned (SchemaName, LogicalName, KeyAttributes, EntityKeyIndexStatus) and clarifies that EntityKeyIndexStatus tracks async index build progress. No contradictions with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise: 4 sentences total. The first sentence states the core purpose, the second gives usage context, the third enumerates return fields, and the fourth provides a cross-reference to a sibling tool. Every sentence adds unique value, with no redundancy or unnecessary detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (few parameters, read-only nature, and presence of output schema), the description covers all necessary aspects: what it does, what it returns, a practical usage hint, and a connection to a related tool. It does not need to explain return values as the output schema presumably does. The description feels complete for an agent to select and invoke 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 already provides descriptions for all three parameters (dataverse_url, table_logical_name, top). The description does not add any additional semantic information about these parameters. Since schema coverage is high (descriptions exist in schema), the baseline is 3, and the description adds no extra value here.
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 specific action: 'List alternate keys (EntityKeyMetadata) defined on a Dataverse table.' The verb 'list' and the target 'alternate keys' are precise. Among siblings like dataverse_list_views or dataverse_list_tables, this uniquely identifies a distinct resource type, so the tool is well differentiated.
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 the purpose of alternate keys ('let integration tools upsert records by business values instead of GUIDs'), giving context for when to use the tool. It also advises to use the LogicalName output with dataverse_delete_alternate_key for removal. However, it does not explicitly state when not to use or compare to other list tools, though the uniqueness of the resource makes that less critical.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List model-driven apps (AppModule records) in a Dataverse environment.
Returns appmoduleid, name, uniquename, description, publish state, and statecode. Set include_unpublished=true to also return draft apps not yet visible to users. Use dataverse_get_app to inspect a single app's components.
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, meaning the description doesn't need to cover safety. The description adds value by listing returned fields and parameter behavior, but doesn't reveal additional behavioral traits beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences with clear structure: purpose, return fields, and parameter guidance. Front-loaded and efficient with 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?
With output schema present, the description doesn't need to detail return values but covers key fields and the main parameter. It mentions a sibling tool for next steps. Lacks mention of pagination or the `top` 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?
Schema description coverage is 0% according to context, so the description must compensate. It explains the `include_unpublished` parameter and lists return fields, but doesn't describe `dataverse_url` or `top` beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists model-driven apps (AppModule records) and lists the returned fields. It distinguishes from sibling `dataverse_get_app` for inspecting a single app.
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 `include_unpublished` and references `dataverse_get_app` for deeper inspection. While it provides good context, it could be more explicit about when to choose this listing over other list tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List asyncoperation (system job) records in the Dataverse environment.
Returns asyncoperationid, name, operationtype, statecode, statuscode, message, friendlymessage, startedon, completedon, createdon, modifiedon, and _regardingobjectid_value. Also includes statecode_label and statuscode_label for human readability. Filter by state_code (0=Ready,1=Suspended,2=Locked,3=Completed), status_code (0=WaitingForResources,10=Waiting,20=InProgress,21=Pausing, 22=Canceling,30=Succeeded,31=Failed,32=Canceled), or operation_type (raw int). Use dataverse_get_async_operation for full details on a specific job.
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate read-only, idempotent, and non-destructive. The description adds context by listing returned fields and explaining filter parameters, but doesn't disclose pagination or performance characteristics.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is concise: one line for purpose, one for returned fields, one for filters, and one for sibling guidance. No wasted words and front-loaded with key information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Output schema exists, so return value documentation is not required. The description covers purpose, available fields, and filters adequately for a list operation.
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 high (each parameter has descriptions). The description adds value by listing common operation_type integers and clarifying state_code/status_code values, but many details are already in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'List asyncoperation (system job) records' and lists returned fields. It distinguishes from sibling 'dataverse_get_async_operation' by noting that tool provides full details on a specific job.
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 specifies when to use this tool vs. the get tool: 'Use dataverse_get_async_operation for full details on a specific job.' This provides clear alternative guidance, though it doesn't explicitly state 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.
Query the audit table with optional OData filters.
Returns audit records from the 'audits' entity set. Common columns:
auditid, createdon — record identity and timestamp
operation — 1=Create, 2=Update, 3=Delete, 4=Access, 5=Upsert
action — specific event code (e.g., 1=Create, 2=Update, 3=Delete, 64=User Access via Web, 65=User Access via Web Services)
objecttypecode — logical name of the audited entity (e.g., 'account')
_userid_value — GUID of the user who made the change
_objectid_value — GUID of the audited record
transactionid — groups related changes in one operation
Use dataverse_get_audit_details to fetch full before/after values for a specific audit record.
Note: requires auditing enabled on the org. If auditing is disabled, Dataverse may return an empty result set or an HTTP error.
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and idempotentHint=true. The description adds that the tool requires auditing enabled and may return empty or error if disabled. It also explains the meaning of operation and action codes. This adds behavioral context beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured: a one-line summary, a bullet-like list of columns, usage guidance, and a prerequisite note. Every sentence adds value without 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 the presence of an output schema and rich annotations, the description covers the tool's purpose, parameters, usage context, and a related alternative. It is fully adequate for an AI agent to understand and invoke the tool 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 already contains detailed descriptions for each parameter (e.g., filter examples, default values). The description provides an overview of common columns but does not add significant meaning beyond what the schema provides. Since schema coverage is effectively complete, a baseline of 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 it queries the audit table with OData filters and returns audit records. It lists common columns and distinguishes from the sibling tool dataverse_get_audit_details, which fetches detailed before/after values. The purpose is specific and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Description explicitly tells when to use this tool and when to use the alternative dataverse_get_audit_details. It also warns that auditing must be enabled, and describes the consequence if disabled. This provides clear context and exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List business units in the Dataverse environment.
Returns businessunitid, name, parent business unit, disabled flag, and modifiedon. Use filter to narrow results (e.g., "isdisabled eq false").
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is clear. The description adds that the tool returns specific fields, which is useful but does not disclose other behavioral traits like pagination behavior or error handling. With annotations covering the core safety, a 3 is appropriate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loading the core purpose and then providing optional usage detail. Every sentence adds value without redundancy, making it efficient and easy to scan.
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 annotations, a well-defined schema, and an output schema, the description covers the essential purpose and return fields. It briefly addresses filtering but does not mention other common aspects like pagination (though top parameter exists) or ordering. This slight gap prevents a perfect score.
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 context indicates 0% schema description coverage, meaning the tool's description does not explain the parameters. The description only mentions the filter parameter with an example, omitting top, select, and dataverse_url. Despite the schema having individual parameter descriptions (which are not counted in coverage by this metric), the description fails to compensate adequately for the low 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 explicitly states 'List business units in the Dataverse environment', clearly identifying the action and resource. It also lists the return fields (businessunitid, name, parent business unit, disabled flag, modifiedon), adding specificity that distinguishes it from other list 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 a usage hint: 'Use filter to narrow results (e.g., "isdisabled eq false")', which helps when to apply filtering. However, it does not mention when not to use this tool or suggest alternative tools (e.g., other list tools for different entities), offering only implicit guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get option values and labels for a Picklist or MultiSelectPicklist column's LOCAL option set.
Use this before filtering records with choice columns — the integer value is required for OData filter expressions (e.g., "statuscode eq 1"). For GLOBAL choices shared across tables use dataverse_get_choice instead. Handles both Picklist and MultiSelectPicklist automatically.
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=true and idempotentHint=true, covering safety. The description adds behavioral details: it handles both Picklist and MultiSelectPicklist automatically and emphasizes local vs global scope. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three concise sentences, front-loaded with the core purpose, and contains no redundant or irrelevant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (local vs global, dual column types, OData filter integration), the description is complete. It covers use case, alternatives, and automatic handling, and an output schema exists so return value explanation is unnecessary.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema itself provides descriptions for all parameters, so baseline is 3. The tool description adds minimal extra parameter meaning beyond the schema (e.g., mentioning that integer values are required for filters, but this is not directly a parameter clarification).
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 'Get' and the specific resource 'option values and labels for a Picklist or MultiSelectPicklist column's LOCAL option set,' distinguishing it from the sibling tool dataverse_get_choice for global choices.
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 explicitly tells when to use this tool ('before filtering records with choice columns'), explains the need for integer values in OData filters, and directs users to dataverse_get_choice for global options, providing clear alternative guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List GLOBAL choice (option set) definitions in the Dataverse environment.
Option values and labels are not returned here — use dataverse_get_choice to retrieve the full option set for a specific choice. $filter is not supported by this endpoint; top is applied client-side.
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds behavioral context beyond annotations: it lists only global choices, does not return option values/labels, and notes that $filter is unsupported. This complements annotations (readOnlyHint, idempotentHint) without contradiction, giving the agent a clear understanding of what the tool does and does not provide.
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 (three sentences) with the main purpose front-loaded. Every sentence adds value: defining the resource, stating what is not included, and noting technical constraints. 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?
While the description covers purpose, missing data (options), and limitations, it fails to address the parameters. Given the existence of an output schema (not shown), return format is covered. However, the absence of parameter guidance, especially with 0% schema coverage, leaves the agent underinformed about required and optional inputs.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With schema_description_coverage at 0%, the description must compensate by explaining parameter usage. However, it provides no information about parameters like 'top', 'select', 'dataverse_url', or 'consistency_strong'. The agent must rely solely on the input schema, which lacks descriptions per the context. This is a significant gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'List', the resource 'GLOBAL choice (option set) definitions', and specifies the scope ('in the Dataverse environment'). It explicitly distinguishes from 'dataverse_get_choice' for full option sets, making purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance: when to use (list global choices), what not to expect (no option values/labels, with alternative), and technical limitations ($filter unsupported, top client-side). This clearly differentiates from sibling tools like 'dataverse_get_choice' and 'dataverse_list_choice_column_options'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List column (attribute) definitions for a Dataverse table.
Use attribute_type to narrow by column type (e.g., 'Lookup', 'Picklist'). For full metadata on a single column use dataverse_get_column. For Picklist/MultiSelectPicklist option values use dataverse_list_choice_column_options.
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. Description adds useful context about the consistency_strong parameter and its impact on caching, but no additional behavioral traits beyond what annotations cover.
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?
Extremely concise: 5 lines covering purpose, filtering, and alternatives. Front-loaded with primary action, no fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the existence of an output schema and comprehensive parameter descriptions, the description covers all essential aspects: purpose, filtering via attribute_type, caching behavior, and sibling tool alternatives.
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 descriptions already detail each parameter. Description adds value by explaining usage of 'attribute_type' (common values) and 'consistency_strong' (when to use), but does not repeat schema info.
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 'List column (attribute) definitions for a Dataverse table.' It explicitly distinguishes from sibling tools like dataverse_get_column (single column) and dataverse_list_choice_column_options (picklist options), preventing misuse.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit guidance: use 'attribute_type' to filter, when to use consistency_strong (after metadata changes), and references alternatives for detailed column data or choice options.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List connection references in the Dataverse environment.
Returns connectionreferenceid, logical name, display name, connector ID, connection ID (empty string if not yet assigned), status, and managed state.
Filter by connector_id to find all references for a specific connector type. Filter by statecode=0 to show only active references. Use the connection_id field to identify which references still need a connection assigned — an empty connectionid means the flow or app using it will fail at runtime.
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description goes beyond by explaining that empty connectionid means runtime failure, and it details the returned fields and their meaning. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Concise and well-structured: purpose sentence first, then list of returned fields, followed by practical filtering advice. Every sentence adds value with no 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 the tool's complexity (multiple parameters, filtering, and output), the description covers essential usage scenarios and field meanings. The presence of an output schema further reduces the need to document return structure 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 adds meaningful guidance for using filter, statecode, and connector_id parameters, and interprets the output's connection_id field. It does not detail the 'top' or 'dataverse_url' parameters, but those are straightforward or have defaults.
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 connection references and specifies the exact fields returned (connectionreferenceid, logical name, etc.). It distinguishes itself from sibling tools like dataverse_get_connection_reference by indicating it returns multiple records.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides concrete guidance on when to use each filter parameter (connector_id, statecode) and explains the significance of the connection_id field for runtime failures. Does not explicitly mention when not to use the tool or alternative tools, but the use cases are clearly outlined.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List request parameter records for a Custom API.
Filters by custom_api_id (GUID) to return only parameters belonging to that Custom API. Returns customapirequestparameterid, uniquename, name, displayname, type, isoptional for each record. Type enum: 0=Boolean, 1=DateTime, 2=Decimal, 3=Entity, 4=EntityCollection, 5=EntityReference, 6=Float, 7=Integer, 8=Money, 9=Picklist, 10=String, 11=StringArray, 12=Guid. An optional OData filter expression can further narrow results.
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate read-only and idempotent behavior. The description adds value by listing returned fields and the type enum, but no additional behavioral traits are disclosed beyond what annotations imply.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three concise sentences with key information front-loaded: action, filter, return fields, and type enum. No waste.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the output schema exists, the description adequately covers purpose, filtering, and return data. The type enum mapping is particularly helpful. No gaps for a list 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 already provides detailed descriptions for all parameters (top, filter, custom_api_id, dataverse_url). The description adds only marginal clarification (e.g., 'Filters by custom_api_id'), so baseline 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 it lists request parameter records for a Custom API, with filtering by custom_api_id. However, it does not explicitly differentiate from closely related sibling tools like dataverse_list_custom_api_response_properties.
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 (e.g., filtering by custom_api_id) but does not provide explicit guidance on when to use this tool versus alternatives 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 response property records for a Custom API.
Filters by custom_api_id (GUID) to return only properties belonging to that Custom API. Returns customapiresponsepropertyid, uniquename, name, displayname, type for each record. Type enum: 0=Boolean, 1=DateTime, 2=Decimal, 3=Entity, 4=EntityCollection, 5=EntityReference, 6=Float, 7=Integer, 8=Money, 9=Picklist, 10=String, 11=StringArray, 12=Guid. An optional OData filter expression can further narrow results.
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint as false. The description adds value by listing the returned fields and explaining the type enum values (0-12). It does not contradict annotations and provides specific behavioral details about 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 concise with three sentences. It front-loads the purpose, then explains filtering, and finally lists returned fields and enum mappings. Every sentence adds essential information without waste.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the annotations (readOnlyHint, etc.) and the presence of an output schema, the description adequately covers purpose, filtering criteria, return fields, and type enum. It does not need to explain pagination as the schema covers the 'top' parameter. The description fills gaps not covered by structured fields, making it complete for this simple list 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 already includes descriptions for all parameters (dataverse_url, custom_api_id, top, filter) with details like bounds and default values. The description adds value by explaining the enum values for the 'type' field in the response, which is not in the schema. Since schema coverage is high (100% for parameters), the description enhances understanding without redundancy.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'List' and the specific resource 'response property records for a Custom API.' It distinguishes from sibling tools like dataverse_list_custom_apis or dataverse_list_custom_api_request_parameters by specifying it returns properties belonging to a Custom API.
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 that the tool filters by custom_api_id and allows an optional OData filter. It implicitly indicates usage when needing to list response properties of a specific Custom API. However, it does not explicitly state when not to use this tool or mention alternatives, but the context is clear given sibling tool names.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List Custom API records in the Dataverse environment.
Returns customapiid, uniquename, name, displayname, bindingtype, isfunction, isprivate, and allowedcustomprocessingsteptype for each record. Use the optional filter parameter to narrow results with an OData $filter expression (e.g., "isprivate eq false", "isfunction eq true"). bindingtype: 0=Global, 1=Entity, 2=EntityCollection. allowedcustomprocessingsteptype: 0=None, 1=AsyncOnly, 2=SyncAndAsync. Use dataverse_get_custom_api to fetch expanded request parameters and response properties for a specific Custom API.
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, indicating a safe read operation. The description adds value by detailing the returned fields and providing enumeration mappings for bindingtype and allowedcustomprocessingsteptype, which are not in the schema. No contradictions with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, with five sentences that efficiently cover purpose, returned fields, filter usage with examples, enum mapping, and a sibling tool reference. No redundant or unnecessary 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 description sufficiently covers purpose, filter usage, and sibling tool. The schema handles parameter details and the output schema presumably covers return values. Minor omission: no mention of pagination via the top parameter, but it's documented in the schema. Overall, adequate for a list tool with good annotations and schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides descriptions for all three parameters, so the baseline is 3. The description goes beyond by giving concrete filter examples and explaining the numeric values for bindingtype and allowedcustomprocessingsteptype, which are not explained in the schema. Thus it adds meaningful semantic 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 starts with 'List Custom API records' which clearly specifies the verb and resource. It lists the specific fields returned, distinguishing it from sibling tools like dataverse_get_custom_api, which is explicitly mentioned for fetching detailed data for a single API. This makes the purpose highly specific and distinguishable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear guidance on when to use the filter parameter with examples, and explicitly directs users to dataverse_get_custom_api for expanded details of a specific API. While it does not state when not to use this tool, the context is clear enough for the agent to make decisions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List Power Platform environments available to the authenticated user.
Uses the Power Platform admin API — no dataverse_url required. Returns instance_url for each environment, which is the dataverse_url for all other tools. Use this to discover environments before calling environment-specific Dataverse tools.
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds context: uses Power Platform admin API, returns instance_url which is the dataverse_url for other tools. No contradictions.
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 four sentences, front-loaded with the main purpose, and every sentence adds value. No redundant or unnecessary information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (listing with two optional booleans and no output schema), the description is complete: it explains what it does, when to use it, what it returns (instance_url), and how it feeds into other tools. No 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 already provides descriptions for both parameters (expand_addons and expand_capacity). The main description does not add parameter-level details, but given the schema's high coverage (100% for param descriptions), a baseline score of 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 'List Power Platform environments available to the authenticated user', using a specific verb (list) and resource (environments), and distinguishes from sibling tools that operate on Dataverse entities by mentioning the admin API and that no dataverse_url is required.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use: 'Use this to discover environments before calling environment-specific Dataverse tools', and provides a key differentiator (no dataverse_url required). This gives clear guidance for tool selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List model-driven app forms registered in the Dataverse environment.
Returns form metadata: id, name, type, activation state, and default flag. Filter by table_logical_name and/or form_type (2=Main, 4=Quick View, 5=Quick Create, 9=Card). Use dataverse_get_form to inspect a form's layout.
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint, idempotentHint, etc. Description aligns and adds context: returns specific metadata fields and filtering behavior. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three focused sentences: purpose, output description, filtering instructions. No extraneous content, efficient and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers main functionality, filtering options, and output fields. Output schema exists, so return details are handled. Missing pagination parameter 'top' is a minor gap. Annotations reduce need for behavioral detail.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%. Description explains form_type and table_logical_name filtering and common values, but omits 'top' (pagination) and 'dataverse_url' requirements completely. Provides partial but not full parameter 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?
Clear verb 'List' and resource 'forms'. Description specifies the action, what metadata is returned, and distinguishes from sibling 'dataverse_get_form' which inspects a form's layout.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly explains filtering by table_logical_name and form_type with common values. References sibling for deeper inspection. Lacks explicit 'when not to use' but provides solid usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List importjob records, optionally filtered by solution unique name.
The large result XML ('data' column) is excluded from all records by default. Results are ordered by createdon descending (most recent first).
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and idempotentHint. The description adds behavioral details: exclusion of large XML column by default and ordering by createdon descending. This is valuable context beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, front-loaded with main action, no unnecessary words. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a list tool with output schema and annotations, the description covers key behaviors (filtering, exclusion, ordering) that are not fully captured in structured data. May lack explicit pagination details, but schema covers 'top' 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?
Schema descriptions cover all parameters, but the description adds meaning by explaining that the 'data' column is excluded by default (relating to the 'select' parameter) and that 'solution_name' filters results. This enhances understanding of default behavior.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the tool lists import job records with optional filtering by solution name. It does not explicitly differentiate from sibling list tools, but the verb 'list' and resource 'import job records' are specific.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool vs alternatives like dataverse_get_import_job or other list tools. The filtering parameter is mentioned but not contextualized with usage scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List an environment's language codes (LCIDs) — which are usable, which are merely installed.
Call this before writing any localized label. provisioned is the load-bearing answer: those are the LCIDs that are actually ENABLED in this environment and therefore the only ones a LocalizedLabels entry may use (the LanguageCode on a DisplayName / Description label passed to dataverse_create_table, dataverse_create_column, dataverse_create_choice, ...). A LocalizedLabel for a language that is installed but NOT provisioned is rejected or silently dropped, so never assume 1033 (English) is provisioned — verify it.
Three unbound, zero-parameter functions are called CONCURRENTLY and their answers reconciled. THE THREE SETS CAN BE MUTUALLY DISJOINT — on the org this tool was verified against, available was [1033], provisioned was [1033], and installed_packs held 44 OTHER LCIDs not including 1033. Read each for what it literally reports and do not infer one from another:
provisioned (RetrieveProvisionedLanguages) — the LCIDs enabled for use in this environment. THE LOAD-BEARING ONE: this is the set a LocalizedLabels entry may use, and the only one worth deciding anything from.
available (RetrieveAvailableLanguages, container LocaleIds) — what this function reports the environment as offering. Observed live as a SHORT list that matched provisioned exactly and shared nothing with installed_packs; it is NOT "every language whose pack is on the server".
installed_packs (RetrieveInstalledLanguagePacks) — the language packs present on the server. Observed live as by far the largest of the three and DISJOINT from both of the others. A pack being installed does not make its LCID provisioned, and this tool does not know which of them could be.
Each list is echoed exactly as Dataverse sent it (order included, not sorted) with a matching *_count. Two derived diffs are computed only when both of their inputs were read successfully, and are named after the exact subtraction they perform rather than implying one is the actionable answer: available_not_provisioned (available minus provisioned) and installed_not_provisioned (installed_packs minus provisioned). Neither is a list of languages an administrator can simply turn on — provisioning has its own prerequisites — so treat both as leads to investigate, not as a to-do list.
THE THREE CALLS FAIL INDEPENDENTLY. A function that is unavailable or privilege-gated is reported in partial_errors and the others' data is still returned, so ALWAYS read partial_errors before concluding a language is absent — a missing key means "not answered", never "empty". Only a failure of all three yields the standard {"error": true, "message": ...} envelope.
The three container property names genuinely differ (LocaleIds for the available list; the function's own name for the other two) and all three are LIVE-CONFIRMED. Each is still tried by name and then by shape (a sole list of integers), so a future change degrades rather than lies. sources reports the property each list was actually found under — check it. If a payload cannot be read unambiguously, its keys are OMITTED, normalized is false, and the untouched body appears under raw_responses; nothing is fabricated and no empty list is invented.
LCIDs are Windows locale ids (1033 = English (United States), 1036 = French (France), 1031 = German (Germany), 3082 = Spanish (Spain)); they are returned as raw integers and are not mapped to language names here.
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description goes far beyond the annotations, disclosing that three functions run concurrently, can return mutually disjoint sets, fail independently with partial_errors, and that container property names may differ. It also explains derived diffs and raw response handling, providing a rich behavioral picture.
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 lengthy but well-structured and front-loaded with the core purpose. Each paragraph covers a distinct aspect (usage, three functions, failure behavior, formatting). Some redundancy and heavy capitalization exist, but the complexity of the tool justifies the detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is exceptionally complete for the tool's complexity, covering the three data sources, their semantics, partial failures, derived diffs, container property names, and output normalization. The presence of an output schema further reduces the need for describing return types, and this description leaves little uncovered.
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 description does not mention dataverse_url, but the schema provides a clear description of the required parameter. Since the single parameter is straightforward and self-explanatory, the description adds no additional parameter semantics. Schema description coverage is reported as 0%, but the schema itself adequately documents the parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists an environment's language codes (LCIDs) and distinguishes between usable and merely installed ones. It names the specific verb 'List' and the resource 'languages', effectively differentiating it from other list tools among the siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly instructs when to call this tool ('before writing any localized label') and warns against assuming 1033 is provisioned. It provides clear context on which set (provisioned) is load-bearing and that installed packs are not automatically usable, giving practical guidance without naming alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List plug-in assemblies registered in the environment, optionally filtered.
Results ordered newest-modified first. Use package_id to scope to one plug-in package. The prerequisite chain is: assembly (or package) → plug-in type → processing step → step image.
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds crucial behavioral context beyond annotations: ordering of results and the hierarchical relationship between assemblies, types, steps, and images. The annotations already declare read-only, idempotent, and non-destructive behavior, so the description's additions are valuable but not exhaustive.
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: three sentences that immediately convey the purpose, ordering, and key filtering capability. No unnecessary words 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 the existence of an output schema (not shown) and detailed parameter schema, the description covers the main behavioral aspects (ordering, filtering hierarchy). It could mention that it lists all assemblies in the environment unless filtered, but overall it is sufficiently complete for a listing tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is high (all parameters have descriptive comments in the schema). The tool description does not add new parameter information beyond what's already in the schema, so it meets the baseline of 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 title and description clearly state the tool lists plug-in assemblies, with optional filtering. The description explicitly distinguishes from sibling tools like 'get_plugin_assembly' by implying retrieval of multiple items and providing a hierarchy hint.
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 context on ordering ('newest-modified first') and filtering options ('package_id to scope to one plug-in package'). It also outlines the prerequisite chain, helping the agent understand the data model. However, it does not explicitly mention when not to use this tool or name alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List NuGet-based plug-in packages registered in the environment.
Results ordered newest-modified first. Packages are an alternative to raw assemblies as the first step in the prerequisite chain.
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds ordering ('newest-modified first') and clarifies what packages are (NuGet-based, alternative to assemblies), providing useful behavioral context beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two front-loaded sentences with no filler: the main action is stated first, followed by ordering and alternative role. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the core purpose, ordering, and the role of packages vs assemblies. It does not detail pagination or filtering, but the schema and output schema compensate. For a read-only list tool, this is sufficient.
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 description adds no parameter details beyond the input schema, which itself includes descriptions for all parameters. Per the rule, with high schema coverage, baseline 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 ('List'), the resource ('NuGet-based plug-in packages'), and the scope ('in the environment'). It also distinguishes from raw assemblies, and the sibling 'dataverse_get_plugin_package' contrasts as a single-item retrieval.
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 that packages are an alternative to raw assemblies, providing context on when to use. It does not explicitly state when not to use or list alternatives, but the hint is sufficient for an informed agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List plug-in step images (pre/post entity snapshots) registered against steps.
Use step_id to scope to one processing step.
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=true and destructiveHint=false. The description adds context that images are pre/post snapshots, but no additional behavioral traits such as pagination limits (handled by schema) or authentication needs. With strong annotation coverage, description adds moderate 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?
Two sentences, front-loaded with the primary purpose. No redundant words. Efficiently communicates the core functionality.
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 is a list operation with an output schema, the description is minimal but sufficient. It does not explain return values (handled by output schema) or mention that it is a read operation (annotations cover it). Could be improved by noting that step_id is optional and what happens when omitted.
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 high (all parameters described). The tool description only reiterates step_id usage, which is already in the schema. Adds no new parameter meaning 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 tool lists plug-in step images, explaining they are pre/post entity snapshots. The name and description effectively distinguish it from sibling tools like dataverse_get_plugin_step_image (singular retrieval) and dataverse_list_plugin_steps (lists steps, not images).
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 a guideline for using step_id to scope to one step, but does not explain when to use this tool versus alternatives like dataverse_get_plugin_step_image for a single image or dataverse_list_plugin_steps for steps. Lacks when-not guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List SDK message processing steps registered in the environment.
Use plugin_type_id to scope to one plug-in type, or message_id to scope to one message. Results ordered by name ascending.
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds ordering behavior ('Results ordered by name ascending') and scoping options, but does not disclose whether results are paginated or if specific permissions are required. Given annotation coverage, this is adequate but not rich.
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: two sentences, 33 words. It front-loads the purpose in the first sentence and adds details in the second. No redundant phrases or 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 has an output schema (covering return values) and good annotations, the description covers purpose, scoping, and ordering. It omits mentioning pagination (though 'top' parameter exists) but is otherwise complete for a list operation.
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 high coverage with descriptions for each parameter (e.g., 'top', 'filter', 'plugin_type_id'). The tool description adds that results are ordered by name ascending, which is not in the schema. With schema coverage high, baseline is 3, and the addition provides marginal extra 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 clearly states 'List SDK message processing steps registered in the environment.' It uses a specific verb ('List') and resource ('SDK message processing steps'), and distinguishes from siblings like dataverse_get_plugin_step (singular) and other list 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 guidance on when to use: 'Use plugin_type_id to scope to one plug-in type, or message_id to scope to one message.' It also mentions ordering. However, it does not explicitly state when not to use it or contrast with alternatives like get_plugin_step for a single step.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List plug-in trace log records with optional filters.
Returns trace and exception information generated by plug-ins and custom workflow activities. Records are ordered newest-first.
Useful filters:
type_name: partial match on the plug-in class name (typename)
exceptions_only: true to show only failed executions
hours_ago: narrow to recent logs (e.g. 1 for the last hour)
message_name: filter by triggering message (e.g. 'Create', 'Update')
primary_entity: filter by entity the plug-in ran against
Plug-in trace logging must be enabled via dataverse_set_plugin_trace_log_setting before logs will be generated. Use dataverse_get_plugin_trace_log_setting to check the current setting.
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint, idempotentHint, and destructiveHint false. Description adds that records are ordered newest-first and returns trace/exception information. No contradictions, and the additional ordering detail is valuable.
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?
Description is well-structured with clear paragraphs: purpose, return info, useful filters list, and prerequisite notes. Slightly verbose with bullet-like formatting, but front-loaded and efficient overall.
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 of 8 parameters, presence of output schema, and sufficient annotations, the description covers filters, ordering, and prerequisites. It could mention pagination (top parameter behavior), but output schema likely covers return structure.
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?
Despite 0% schema description coverage, the tool description provides detailed explanations for key parameters (e.g., partial match for type_name, examples for hours_ago and message_name, exclusion filter for exceptions_only). This adds significant meaning beyond the schema's parameter names and types.
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 explicitly states 'List plug-in trace log records with optional filters', clearly identifying the verb and resource. It distinguishes from sibling tools like dataverse_get_plugin_trace_log_setting and dataverse_set_plugin_trace_log_setting by focusing on listing logs with filters.
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?
Description provides explicit usage guidance: prerequisite to enable logging via dataverse_set_plugin_trace_log_setting, and how to check setting with dataverse_get_plugin_trace_log_setting. It also lists useful filters, helping the agent decide when to use this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List plug-in types (.NET classes) registered in the environment.
Use assembly_id to scope to one assembly. Results ordered by typename ascending. Types are the second step in the prerequisite chain: assembly → type → step → image.
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds the ordering (by typename ascending) and the prerequisite chain, which are behavioral traits not covered by annotations. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, front-loaded with the main purpose, no redundant information. Every sentence adds value: purpose, scoping, ordering, and prerequisite 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?
Output schema exists, so return values are covered. The description includes the prerequisite chain, which helps agents understand context. It could mention filtering options like typename_contains or is_workflow_activity, but these are in the schema, so it is acceptable.
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?
Input schema descriptions are comprehensive (e.g., 'GUID of a pluginassembly; return only types in that assembly'). The description adds only the ordering detail (ascending by typename), which is a minor addition. Baseline 3 is appropriate since schema does the heavy lifting.
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 plug-in types (.NET classes) registered in the environment, using a specific verb 'List' and resource 'plug-in types'. It distinguishes from sibling tools like dataverse_get_plugin_type (single) and dataverse_list_plugin_assemblies (different entity).
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 using assembly_id to scope results, providing context for when to filter. It also places the tool in a prerequisite chain (assembly → type → step → image). However, it does not explicitly state when not to use this tool or list alternatives, so it loses one point.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List runtime performance statistics for Dataverse plug-in types.
Returns execution counts, failure rates, crash metrics, and worker-process termination contribution percentages per plug-in type. Records are populated by Dataverse within 30–60 minutes of plug-in execution; all fields are read-only.
Filter to a specific plug-in type with plugin_type_id, or omit to return statistics for all plug-in types. Set include_plugin_type_details=true to expand each row with the plug-in type name, typename, and assemblyname.
Use this to identify slow, high-failure, or crash-prone plug-ins before investigating further with the Power Platform Admin Center analytics dashboard.
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint, idempotentHint, and destructiveHint=false. The description adds valuable behavioral context: records are populated within 30-60 minutes, all fields are read-only, and specifies the exact metrics returned. No contradictions with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise at four sentences, with the main purpose in the first sentence followed by supporting details. Every sentence adds value without 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 to define return values, the description covers the key aspects: what metrics are returned, latency, filtering options, and use case. It is complete for a filtered listing tool with good annotation support.
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 description explains the purpose of plugin_type_id and include_plugin_type_details, adding meaning beyond the schema. However, it doesn't mention the 'top' parameter or 'dataverse_url'. Schema descriptions exist for all parameters, but the tool description only covers two of the five parameters.
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 that the tool lists runtime performance statistics for Dataverse plug-in types, specifying exactly what metrics are returned (execution counts, failure rates, crash metrics, contribution percentages). It distinguishes itself from sibling tools like dataverse_list_plugin_types by focusing on performance statistics rather than just listing 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?
The description provides clear context for when to use this tool: to identify slow, high-failure, or crash-prone plug-ins before investigating further. It mentions filtering options and a follow-up action (Power Platform Admin Center). However, it doesn't explicitly say when not to use it or name alternative tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the privileges DEFINED in the environment — the catalogue of what CAN be granted.
This is the reference list, not an assignment. dataverse_get_role_privileges, dataverse_get_team_privileges and dataverse_retrieve_user_privileges answer "who HOLDS what"; this answers "what privileges exist, what access right does each carry, and at which depths can it be granted". Use it to look up the privilege behind a name those tools return ('prvReadAccount'), or to enumerate everything that exists for one table.
ACCESS RIGHTS ARE DECODED BY A HAND-ROLLED MAP, AND THAT IS THE POINT. The accessright column is an integer with NO option set behind it anywhere in Dataverse: the PicklistAttributeMetadata cast 404s, GlobalOptionSetDefinitions for it 404s, and annotation-included FormattedValues return only the integer with thousands separators. So access_right_name comes from a map derived empirically and cross-checked across every privilege in the environment: 0 None · 1 ReadAccess · 2 WriteAccess · 4 AppendAccess · 16 AppendToAccess · 32 CreateAccess · 65536 DeleteAccess · 262144 ShareAccess · 524288 AssignAccess The gaps are real (8 and 16-32768 are unused), so a name is never derived by shifting bits. AN UNRECOGNISED VALUE IS REPORTED RAW: access_right still carries it, access_right_name is ABSENT, and the value is listed under unmapped_access_rights. Nothing is invented — a wrong access-level label is more dangerous than an unlabelled one, the same discipline dataverse_get_team_privileges applies to Depth. accessright 0 marks the non-CRUD privileges (prvActOnBehalfOf... and friends); it is a real value, not "unknown".
depths COLLAPSES THE FOUR canbe* FLAGS into one ordered list, e.g. ["Basic","Local","Deep","Global"] — the depths at which that privilege may be granted, by increasing scope (Basic = the user's own records, Global = org-wide). Only six combinations exist in practice and nearly every privilege allows Global. An EMPTY depths list is unexpected and means the flags could not be read, not that the privilege can be granted nowhere.
total_count COMES FROM AN AGGREGATION, NOT @odata.count. On this collection @odata.count CAPS AT 5,000 and lies — ?$count=true reports 5,000 where the true catalogue is ~7,346 — so the count is taken with $apply=aggregate($count as c), which bypasses the cap. If a trustworthy total cannot be obtained, total_count is OMITTED and message says so; a capped number is never reported as the truth. count is the size of the returned page, has_more says whether anything was trimmed.
TABLE SCOPING GOES THROUGH A JOIN TABLE, NOT THROUGH PRIVILEGE NAMES. Passing table_logical_name queries privilegeobjecttypecodesset, whose objecttypecode column holds the table's LOGICAL NAME STRING. Filtering by name instead — endswith(name,'Account') — is WRONG in general even though it looks right on the tables people test with: endswith(name,'Role') returns 25 privileges spanning FOUR different tables (role, connectionrole, relationshiprole, mspp_webrole). Privileges are also many-to-many with tables (one privilege can map to as many as 14), which a name can never express. That join table is private and undocumented, so if it fails you get a clear error naming it — never a silent fall back to name matching.
AN UNKNOWN TABLE NAME IS AN ERROR, NOT AN EMPTY LIST. objecttypecode is an EntityName column, so Dataverse validates it: an unknown, misspelled or plural logical name answers HTTP 400 [0x80041102] "The entity with a name = '…' with namemapping = 'Logical' was not found in the MetadataCache", naming the offending entity — that message is the reliable signal for a bad table name, and it is what the error surfaces first. Casing is never the cause: table_logical_name is lowercased for you, matching name_startswith's case-insensitivity on both routes. An EMPTY privileges list means the opposite — the table EXISTS and genuinely has no privileges mapped to it, live-confirmed on 'privilege' itself, which returns 0.
source names the route that actually ran ('privileges' or 'privilegeobjecttypecodesset'); the response shape is identical either way. On the join route, name_startswith and access_right are applied client-side, so count/total_count describe the filtered set.
Each entry: name, privilege_id, access_right (raw integer), access_right_name (absent when unknown), depths, can_be_entity_reference, can_be_parent_entity_reference. Bulky and empty columns are deliberately dropped (privilegetype does not exist on this entity at all).
If the response carries no readable collection, nothing is guessed: normalized is false, no counts are reported, and the body comes back under raw_response. An empty privileges list with normalized: true is a real answer; a missing container is not.
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark this readOnly, openWorld, idempotent and non-destructive; the description adds substantial context beyond those flags: a hand-rolled access-right map with unmapped values reported raw, @odata.count capping at 5,000 bypassed by aggregation, join-table scoping versus name-matching, and explicit error behavior for unknown table names. It also states the response's normalization discipline (empty list is real, missing container is not), so no guesswork is left to the agent.
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 long, but it is organized into capitalized topic paragraphs and every paragraph introduces a behavioral nuance the agent must know (access-right decoding, depth collapsing, count aggregation, join-table scoping, error semantics). It is front-loaded with the core purpose and only then dives into edge cases; still, it is verbose enough that some agents might need to parse several paragraphs for a simple list operation.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The output schema exists, so return-value details need not be spelled out; the description instead covers failure modes, count accuracy, route differences, and normalization semantics. Combined with rich parameter docs in the input schema, the description leaves virtually no ambiguity about when and how to invoke this 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 schema already documents each parameter with detailed descriptions (case-insensitivity, join-table scoping, 'None' as a real value), so the baseline is high. The tool description reinforces and extends this by explaining the integer mapping for access_right, that name_startswith is case-insensitive on both routes, and what total_count/count/has_more mean for top, adding meaning beyond the structured 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 opens with a crisp active statement: 'List the privileges DEFINED in the environment — the catalogue of what CAN be granted.' It explicitly contrasts with dataverse_get_role_privileges, dataverse_get_team_privileges, and dataverse_retrieve_user_privileges, stating those answer 'who HOLDS what' whereas this answers 'what privileges exist, what access right does each carry, and at which depths can it be granted.' This is a specific verb+resource with clear sibling 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?
The description names the sibling tools that answer 'who HOLDS what' and tells the agent to use this tool as the reference catalogue: 'Use it to look up the privilege behind a name those tools return... or to enumerate everything that exists for one table.' It also gives concrete guidance about when to apply table_logical_name and warns against name-based filtering, making the usage context explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List classic processes (workflows, business rules, actions, BPFs) from the workflow entity.
Classic process categories: 0=Workflow, 1=Dialog, 2=Business Rule, 3=Action, 4=Business Process Flow. Use the category parameter to filter by a specific category. Cloud flows (category 5) are excluded by default unless you explicitly set category=5.
By default returns only type=1 (definition) records to avoid duplicate activation/template rows. Set type=None to return both types.
Use filter for additional OData conditions (e.g., "statecode eq 1" for activated processes only, or "primaryentity eq 'account'").
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations (readOnlyHint, idempotentHint, destructiveHint) are consistent. Description adds significant context: default type=1 to avoid duplicates, exclusion of category 5, and additional OData filter support. No 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?
Well-structured with bullet-style explanation of categories and filters. Content is justified but could be trimmed slightly without losing clarity.
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?
Covers all key aspects: default exclusions, parameter usage, filter examples, and output projection. Output schema exists, so return values are documented. Adequate for an agent to select and invoke 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?
Schema coverage is high with descriptions. The description adds value by explaining default behaviors (type defaults to 1, category excludes 5) and providing filter examples, going beyond schema 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?
Description clearly states it lists classic processes (workflows, business rules, actions, BPFs) from the workflow entity, with specific verb and resource. It distinguishes from siblings like dataverse_get_cloud_flows by explicitly excluding cloud flows unless requested.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides when-to-use guidance (list classic processes) and when-not (cloud flows excluded by default). Includes details on category and type filters but lacks explicit mention of alternative tools for specific scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List relationship definitions for a table (OneToMany, ManyToOne, ManyToMany) or the whole environment.
Use the returned SchemaName with dataverse_get_relationship for full cascade and navigation property details. Navigation property names from the results are required for OData $expand queries and for dataverse_associate_records.
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so description adds value by explaining how results are used (for $expand and associate_records) but does not disclose additional behavioral traits beyond what annotations cover.
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 concise sentences with no wasted words. Front-loaded with purpose, followed by actionable guidance on using results.
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?
Description covers purpose, scope, and usage hints. Output schema exists so return structure is documented elsewhere. Complete for a listing tool with proper annotations.
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?
Input schema provides detailed descriptions for all parameters; description does not add further parameter meaning. Baseline 3 due to high schema description 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?
Description clearly states it lists relationship definitions (OneToMany, ManyToOne, ManyToMany) for a table or whole environment. It distinguishes from sibling dataverse_get_relationship by directing users to that tool for full details.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says when to use (list relationships) and mentions navigation property names are needed for $expand and associate_records. Provides an alternative (use returned SchemaName with get_relationship). Does not explicitly state when not to use, but context of sibling tools makes it clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List SDK message filters showing which entities support each message.
Use message_id to scope to one message, or primary_entity to see all messages supported by one table. Use dataverse_get_sdk_message_filter to resolve a specific filter_id for dataverse_create_plugin_step.
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, indicating safe read-only behavior. The description adds no additional behavioral context (e.g., pagination limits, return structure) beyond the purpose, so it does not exceed what annotations already convey.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences, front-loading the purpose, then providing usage guidance and sibling references. Every sentence adds value with 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?
Combined with annotations (safety profile) and output schema (return values covered), the description is sufficient for this listing tool. It explains the primary use cases and scoping, and references an alternative tool for more specific operations.
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 description adds useful context for message_id and primary_entity parameters beyond the schema descriptions ('scope to one message', 'see all messages supported by one table'). Schema descriptions for other parameters (top, filter, select) are already clear, and the description does not add significantly to those. Overall, it enhances understanding without being redundant.
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 SDK message filters showing which entities support each message. It differentiates from sibling tools like dataverse_get_sdk_message_filter (for resolving a specific filter) and dataverse_list_sdk_messages (for listing messages) by specifying the output and usage.
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 explicitly advises when to use this tool: 'Use message_id to scope to one message, or primary_entity to see all messages supported by one table.' It also directs to a sibling tool (dataverse_get_sdk_message_filter) for resolving a specific filter_id, providing clear when-to-use vs. alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List SDK messages — the catalog of operations plug-in steps can intercept.
Use to discover valid message names (e.g. 'Create', 'Update', 'Assign') before calling dataverse_get_sdk_message to resolve message_id for a step.
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the description does not need to restate safety. The description adds context that this tool is used for discovery, but does not disclose additional behavioral traits such as pagination, authorization needs, or performance implications. The bar is lower due to annotations, but the description offers no extra transparency beyond what annotations provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description consists of two concise sentences. The first sentence states the core purpose, and the second provides usage context with examples. No redundant or irrelevant information is included, and the key details are front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has an output schema, so the description does not need to explain return values. The description adequately covers when to use the tool and how its output feeds into another tool. Given its simplicity and the presence of annotations, the description is complete and sufficient for an agent to use the tool 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 provides detailed descriptions for all parameters (top, filter, select, dataverse_url, name_contains). Despite the context signal of 0% schema description coverage, the actual schema has clear descriptions. The tool description does not add parameter-level meaning beyond the schema, so the baseline score of 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 defines the tool as listing SDK messages, which are the catalog of operations plug-in steps can intercept. It distinguishes the tool from its sibling dataverse_get_sdk_message by stating it is used to discover valid message names before resolving a message_id, preventing 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?
The description explicitly states when to use the tool: to discover valid message names (e.g., 'Create', 'Update', 'Assign') before calling dataverse_get_sdk_message. It provides a clear workflow and implies when not to use it (i.e., not for resolving specific message IDs).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List security roles in the Dataverse environment.
Returns roleid, name, businessunitid, managed status, and modifiedon. Use filter to narrow results (e.g., "ismanaged eq false"). Use dataverse_get_security_role for full details on a specific role.
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate read-only, idempotent, non-destructive. Description adds specific returned fields and filter behavior, enhancing beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Four concise lines, front-loading purpose and key details with no superfluous content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With output schema present and thorough annotations, the description covers essential usage without gaps; minor missing details like pagination are not critical.
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 provides descriptions for all parameters (100% coverage), so description adds no additional parameter insight beyond mentioning default select columns.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the action ('List security roles') and the resource ('Dataverse environment'), and distinguishes from sibling dataverse_get_security_role for full details.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly mentions using filter to narrow results and directs to dataverse_get_security_role for specific roles, providing clear context without exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List components within a Dataverse solution, with human-readable type names.
Use component_type to filter by type code (1=Entity, 61=Web Resource, 300=Canvas App, 91=Plugin Assembly, 92=SDK Message Processing Step).
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds that it returns human-readable type names, which is useful behavioral context, but does not elaborate on pagination, default top value, or any rate limits. With annotations carrying the burden, this is adequate but not exceptional.
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: two sentences. The first sentence states the primary action, and the second provides actionable filtering guidance. Every sentence earns its place with zero wasted words. Structure is optimal for quick understanding.
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, clear annotations, and an output schema, the description covers the essential purpose and filtering. It mentions human-readable type names and provides key type codes. It could briefly mention the default top value or that results are paginated, but these are already in the schema. Overall, it is complete enough for smooth 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?
The input schema descriptions already cover all parameters (top, solution_id, dataverse_url, component_type) with full detail. The description only restates some type codes for component_type and adds the concept of human-readable names. Since schema coverage is effectively high, the description adds marginal value, warranting a baseline 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 clearly states 'List components within a Dataverse solution', which is a specific verb+resource combination. It distinguishes from sibling tools like dataverse_list_solutions by focusing on components within a solution, and adds value by mentioning human-readable type names.
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 a clear context for using the tool ('List components within a Dataverse solution') and gives explicit filtering instructions for component_type with common codes. However, it does not mention when not to use this tool versus alternatives (e.g., using specific getters for individual components) or provide any exclusion criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List solution history records from msdyn_solutionhistories.
Tracks import, upgrade, and export operations on solutions. Optionally filter by solution_id or solution_unique_name (mutually exclusive). solution_id is resolved to the solution unique name first, then used to filter history records via msdyn_name. Omit both to list all.
The msdyn_suboperation field distinguishes operation sub-types:
3: Import/Update (in-place overlay; obsolete components are NOT deleted)
5: Upgrade-with-deletion (DeleteComponents phase; obsolete components ARE deleted)
Use msdyn_suboperation to determine whether a history record represents a standard update or a true upgrade with component deletion.
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds behavioral details: resolution logic (solution_id resolved to unique name first), filtering via msdyn_name, and suboperation field semantics. This goes beyond annotations to explain data interpretation.
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, front-loading the purpose, then detailing filters, then field semantics. Every sentence is informative. No fluff.
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 (not shown), the description covers filtering options, parameter constraints, and field interpretation (msdyn_suboperation). It fully explains the tool's behavior and is sufficient 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?
Although the input schema has good descriptions, the description adds value by explaining the mutual exclusivity of solution_id and solution_unique_name, the resolution process, and that omitting both lists all. It also references the default projection for the select parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it lists solution history records from msdyn_solutionhistories, tracking import, upgrade, and export operations. This specific verb+resource distinguishes it from sibling tools like dataverse_get_solution_history.
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 (to track solution operations), the mutual exclusivity of filters (solution_id and solution_unique_name), and the meaning of msdyn_suboperation. It lacks explicit when-not-to-use or alternatives, but provides clear context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List solutions in the Dataverse environment with name, version, and managed status.
Use filter to narrow results (e.g., "ismanaged eq false"). Use dataverse_get_solution for full details on a specific solution.
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, etc. The description adds the filtering behavior and output fields but does not mention pagination or that results might be limited by the top parameter. Some useful context beyond annotations, but not extensive.
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 that efficiently cover purpose, usage, and alternative. No redundant or extraneous information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of an output schema and comprehensive annotations, the description covers the key points: purpose, filtering, and alternative tool. It could mention pagination or the required dataverse_url, but these are in the schema. Sufficient for most use cases.
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 description mentions the filter parameter, but the input schema already provides thorough descriptions for all parameters (top, filter, select, dataverse_url). The description adds minimal additional meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('List solutions') and the resource ('in the Dataverse environment'), and specifies the output fields (name, version, managed status). It distinguishes itself from siblings like dataverse_get_solution by indicating it's a broad listing tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly advises using the filter parameter with an example, and directs to dataverse_get_solution for full details. This provides clear when-to-use and when-not-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List tables (entities) in the Dataverse environment with their logical names and display names.
Use filter to narrow results (e.g., "IsCustomEntity eq true" for custom tables only). Use dataverse_get_table_metadata for full schema details on one table. Use dataverse_get_entity_sets to discover OData collection names for record queries.
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior. The description adds filter usage context and default select properties, but does not disclose additional behavioral traits like caching, pagination, or performance implications.
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 with three sentences: first states the purpose, second gives filter usage, third references sibling tools. 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 presence of an output schema and annotations, the description is sufficient. It explains what is returned, how to filter, and where to find more detailed information.
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 description adds value by explaining the filter parameter with examples and mentioning the default select properties. However, it does not cover top, dataverse_url, or consistency_strong beyond what the schema already 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 it lists tables with their logical and display names. It distinguishes itself from sibling tools by referencing dataverse_get_table_metadata and dataverse_get_entity_sets for more specific needs.
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 explicitly provides when-to-use guidance with filter examples and directs to specific sibling tools for full schema details or OData collection names, helping the agent choose correctly.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List teams in the Dataverse environment.
Returns teamid, name, teamtype, businessunitid, and modifiedon. Use filter to narrow results (e.g., "teamtype eq 0" for owner teams). Use dataverse_get_team for full details on a specific team.
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare the tool as read-only, idempotent, and non-destructive. The description adds context about the returned fields and filtering behavior, which is useful but not critical beyond annotations. No contradictions.
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 at four sentences, front-loading the purpose and key guidance. It avoids redundancy and is well-structured, though could be more compact without losing information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of an output schema and comprehensive annotations, the description covers the essential purpose and filtering guidance. However, it fails to explain the 'top' and 'select' parameters, leaving some gaps for a tool with multiple parameters and 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?
With 0% schema description coverage (despite schema containing descriptions, per context), the description only partially compensates by explaining the filter parameter. It omits details on 'top', 'select', and 'dataverse_url', leaving the agent without enough context for proper usage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists teams in Dataverse, specifies returned fields, and distinguishes from the sibling tool 'dataverse_get_team' for full details. The verb 'list' and resource 'teams' are specific and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description advises using the filter parameter to narrow results and directs users to 'dataverse_get_team' for full details, providing clear guidance on when to use this tool versus an alternative. It lacks explicit 'when not to use', but the context is sufficient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List system users (systemusers) in the Dataverse environment.
Returns systemuserid, fullname, domainname, email, disabled flag, and businessunitid. Use filter to narrow results (e.g., "isdisabled eq false", "domainname eq 'user@contoso.com'"). Use dataverse_get_user for full details on a specific user.
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and idempotentHint=true, so the description adds minimal behavioral context beyond confirming it's a read operation. No contradictions, but description doesn't expand on safety or side effects beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Four sentences, front-loaded with the main action and resource. Each sentence adds distinct information (purpose, returned fields, filtering guidance, alternative tool). 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?
Given the presence of an output schema and the tool's straightforward nature (list with filter/pagination), the description covers key aspects: what it returns, how to filter, and when to use an alternative. Leaves no 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 provides detailed descriptions for all parameters. The description adds value by giving concrete filter examples (e.g., 'isdisabled eq false') and clarifying default return columns, which enhances usability beyond the schema 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 clearly states the action 'List system users' and identifies the resource type, distinguishing it from the sibling tool 'dataverse_get_user' for full details. It lists returned fields, making the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides guidance on using the filter parameter to narrow results and explicitly recommends using 'dataverse_get_user' for full details on a specific user. No explicit when-not-to-use, but sufficient context for agent decision.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List saved views (savedqueries) registered in the Dataverse environment.
Returns metadata: id, name, querytype, isdefault, statecode. Filter by table_logical_name and/or query_type (0=Main Grid, 1=Advanced Find, 2=Associated, 4=Quick Find, 64=Lookup). Use dataverse_get_view for layout.
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate read-only, idempotent, and non-destructive behavior. Description reinforces by stating it returns metadata and does not modify data. Adds context about return fields beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Four sentences, each serving a clear purpose: purpose, return fields, filter guidance, and cross-reference. No redundancy, front-loaded with key information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers return metadata and filtering adequately. For a list tool with output schema, it is sufficiently complete. Could mention default top value or pagination, but not essential.
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?
Description adds minimal value over input schema descriptions. It lists filter options concisely, but the schema already provides equivalent detail. No additional parameter context beyond existing 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?
Description clearly states it lists saved views (savedqueries) and returns specific metadata fields. It differentiates from sibling tools like dataverse_get_view, which retrieves layout details.
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?
Explains filtering by table_logical_name and query_type with value mappings. Suggests using dataverse_get_view for layout, providing context on when to use an alternative. Lacks explicit exclusion criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List webresource records in the Dataverse environment.
Returns webresourceid, name, displayname, webresourcetype (+ label), description, languagecode, ismanaged, iscustomizable, createdon, modifiedon. Content is excluded from list results (it can be very large); use dataverse_get_web_resource with include_content=true to retrieve it. Filter by web_resource_type (1=HTML, 2=CSS, 3=JScript, 4=XML, 5=PNG, 6=JPG, 7=GIF, 8=XAP, 9=XSL, 10=ICO, 11=SVG, 12=RESX) and/or name_contains for a case-sensitive substring match on the name field. After creating or updating a web resource, call dataverse_publish_customizations to make changes live.
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=true, idempotentHint=true. The description adds value by detailing the returned fields (webresourceid, name, etc.) and explaining that content is excluded and why, which goes beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, well-structured with enumerated output fields and clear filtering options. Every sentence adds value without redundancy, making it easy for an AI agent 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 (list with filters) and the existence of an output schema, the description covers all necessary aspects: purpose, filters, exclusions, and post-use actions. It is complete and self-contained.
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 descriptions for each parameter, but the tool description adds further context: it lists the mapping for web_resource_type values (1=HTML, etc.) and provides an example for name_contains ('new_/'). This enhances understanding beyond the schema 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 explicitly states 'List webresource records in the Dataverse environment' and clearly distinguishes from sibling tool dataverse_get_web_resource by noting content exclusion and directing to that tool for content retrieval.
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 explicit guidance on when to use this tool (for listing without content) and when to use an alternative (dataverse_get_web_resource for included content). It also advises calling dataverse_publish_customizations after modifications, which adds workflow context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Query records from a Dataverse table with OData filtering, ordering, and expansion.
For a single record by GUID use dataverse_get_record. For just a count use dataverse_count_records. For group-by aggregation use dataverse_aggregate_table. To create, update, or delete records use dataverse_create_record, dataverse_update_record, or dataverse_delete_record.
Always specify select to limit returned columns and keep payloads small.
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and idempotentHint; description adds context about OData capabilities (filtering, ordering, expansion) and payload advice. No contradictions.
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?
Description is two short paragraphs, front-loaded with purpose and usage. No redundant sentences, though could be slightly more streamlined.
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 and the presence of an output schema, the description covers main capabilities, sibling differentiation, and usage advice. Adequate 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?
Input schema provides detailed descriptions for all parameters (coverage 100%); description adds general advice on 'select' but does not enhance semantics beyond what schema already 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 it queries records from a Dataverse table with OData filtering, ordering, and expansion. It distinguishes from siblings by explicitly naming alternatives for single records, counts, aggregation, and CRUD operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit guidance on when to use this tool vs alternatives (e.g., 'For a single record by GUID use dataverse_get_record') and advises on best practice ('Always specify select to limit returned columns').
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Answer "WHY does this principal have access to this record?".
Calls the unbound RetrieveAccessOrigin function, which explains where a principal's rights over one specific row come from — object ownership, or the Principal Object Access (POA) table that backs explicit shares and team or hierarchy grants.
This is the companion to dataverse_retrieve_principal_access, which returns only the access MASK (which rights: Read, Write, Delete, …) and cannot say where those rights came from. When you are debugging "why can this user see this record?" or "why can't they?", the mask is the symptom and this is the cause. Use dataverse_audit_user_access for the wider picture (roles, teams, effective privileges) and dataverse_get_role_privileges for what one role permits in general rather than on one row.
Inputs:
object_id — the record's own GUID.
logical_name — the SINGULAR lowercase logical name of that record's table ('account', not 'accounts'). This is deliberately not the entity set name the record-access tools take.
principal_id — a systemuser id or a team id. No other principal type is accepted; use dataverse_list_users / dataverse_list_teams.
RESPONSE SHAPE (verified live). Dataverse answers with ONE scalar string property, Response — never a collection, in a raw body of roughly 286 bytes. It is surfaced as access_origin, with access_origin_source naming the property it was read from, and the payload (minus the @odata.* envelope) rides along under raw_response so you can check that for yourself. There is no count: the answer is never list-shaped. Should a future platform change move the answer somewhere unrecognizable, normalized is false, nothing is fabricated, and raw_response is the whole answer.
HTTP 200 DOES NOT MEAN "HAS ACCESS" — READ THE STRING. Three materially different outcomes all come back as a successful call with normalized true, and they are distinguishable ONLY by the English prose inside the string. The text is passed through verbatim and deliberately NOT classified into a boolean: pattern-matching platform prose is fragile and locale-dependent, and a wrong security verdict is worse than none. Observed live in ONE org — these wordings are observations, not a documented platform contract, so treat the list as incomplete and never match on it:
Access exists, with the reason. Two forms seen, both meaning "owner" — "PrincipalId is object owner ()" on a user- or team-owned row, and "PrincipalId is member of organization () who is object owner ()" on an ORGANIZATION-owned row (see the org-owned note below for why that answer is the same for every principal).
NO access at all — "Access origin could not be found. Access does not come from POA table or object ownership."
The record DOES NOT EXIST — still HTTP 200, carrying the platform's "Does Not Exist" exception text inside the Response string. A bad object_id is NOT a 404 from this function, so an unread string looks exactly like a successful answer. Do not report that the principal has access unless the string says so.
Other live-confirmed behaviour:
An unknown but grammar-valid logical_name is a clean HTTP 400 [0x80041102] "... was not found in the MetadataCache", surfaced through the standard {"error": true, "message": ...} envelope. Confirm the name with dataverse_list_tables.
On an ORGANIZATION-owned table (solution, role, …) the answer is the same for every principal, because ownership resolves at organization level. That is correct platform behaviour, not a defect — discrimination between principals shows up on user- and team-owned rows.
A nonexistent principal_id is not validated against an org-owned row: it returned the same generic ownership text as a real one. Confirm the principal exists with dataverse_get_user / dataverse_get_team first.
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description goes far beyond the annotations by disclosing critical runtime behavior: 'HTTP 200 DOES NOT MEAN "HAS ACCESS" — READ THE STRING', 'Three materially different outcomes... distinguishable ONLY by the English prose inside the string', and specific error cases like unknown logical_name returning a 400, org-owned rows returning identical answers, and nonexistent principal_id not being validated. It also explains the normalization/raw_response behavior, adding value beyond readOnlyHint and idempotentHint.
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?
Although long, the description is well-structured with clear sections for inputs, response shape, and live-confirmed behavior. Every sentence adds necessary nuance or a critical warning. It is front-loaded with the core purpose and immediately distinguishes from the related mask-only tool. There is no fluff or redundant repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity and the risk of misinterpreting HTTP 200, the description is remarkably complete. It documents the response shape, the meaning of normalized flags, and multiple edge cases (nonexistent records, org-owned rows, invalid principal IDs). It also cautions that observed wordings are not a platform contract, which is crucial for an agent to avoid brittle reasoning.
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 description adds meaning beyond the schema by clarifying logical_name is 'the SINGULAR lowercase logical name... deliberately not the entity set name' and principal_id 'must be a systemuser or a team — no other principal type is accepted.' It covers object_id, logical_name, and principal_id with context. However, it omits dataverse_url from the Inputs section, though the schema already provides a clear description for that parameter. The description meaningfully compensates for the schema's terse descriptions.
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 explicitly frames the tool as answering 'WHY does this principal have access to this record?' and states it 'explains where a principal's rights over one specific row come from — object ownership, or the Principal Object Access (POA) table.' It differentiates from the sibling dataverse_retrieve_principal_access, which returns only the access mask. This is a specific verb+resource+scope with clear 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?
The description provides direct comparisons: 'This is the companion to dataverse_retrieve_principal_access, which returns only the access MASK... When you are debugging "why can this user see this record?"... use this.' It also gives alternatives for broader questions: 'Use dataverse_audit_user_access for the wider picture... and dataverse_get_role_privileges for what one role permits.' It even states principal-type constraints and which list tools to use for valid IDs.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return the access rights a system user has to a specific Dataverse record.
Returns the AccessRights bitmask and named rights (ReadAccess, WriteAccess, DeleteAccess, etc.). Use before delegating an operation to confirm the user can act on the record.
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and destructiveHint, so the description correctly aligns with a safe read operation. It adds value by detailing the output (bitmask and named rights) and the use case for confirming access, which together provide full behavioral transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is brief (under 50 words), well-structured into two paragraphs, and front-loads the core purpose. Every sentence adds value, with no redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the purpose, usage guidance, and output format (bitmask and named rights). With an output schema present, it does not need to detail return values further. Annotations fully cover behavioral traits, making the description complete for a read-only 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 fully describes all four parameters with their own descriptions, so the tool description does not add parameter semantics. The baseline of 3 is appropriate given high schema coverage; the description does not compensate 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 tool returns access rights for a system user to a specific record, with a specific verb 'Return' and resource 'access rights'. The title 'Retrieve Principal Access' reinforces the purpose. It distinguishes from sibling tools like dataverse_retrieve_user_privileges by focusing on a single record.
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 explicitly advises using this tool before delegating an operation to confirm user permissions, providing clear context. However, it does not mention when not to use it or compare with sibling tools like dataverse_audit_user_access or dataverse_retrieve_user_privileges.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieve the full audit change history for a specific record.
Calls the unbound RetrieveRecordChangeHistory function, which returns the same AuditDetailCollection container as its column-scoped sibling dataverse_get_attribute_change_history — the entries sit TWO levels down (AuditDetailCollection -> AuditDetails), not one.
AN HTTP 200 IS NOT PROOF OF ANYTHING, AND ON A 404 READ THE ERROR CODE. Live- confirmed on this function, and the earlier note that auditing being off produces an HTTP error was WRONG:
auditing disabled at organization/table level returns HTTP 200 carrying the audit-configuration rows described below and ZERO genuine changes — not an error, and no error message to read;
MOST tables do NOT validate that the target record exists: a well-formed but NONEXISTENT record id with the CORRECT plural entity set returns HTTP 200 with zero genuine changes (12 of 15 entity sets swept on one org behaved this way, 'accounts' among them). An empty answer is therefore never evidence that the record is there, or that it never changed;
a 404 is NOT automatically a naming mistake — the error CODE decides. [0x80060888] "Resource not found for the segment ''" NAMES the bad segment: the entity set is wrong (typically the singular slipped in for the plural) or that table is not provisioned on this org, so fix the name with dataverse_get_entity_sets rather than hunt a deleted row. [0x80048d02] has been seen instead from a CORRECT plural entity set ('audits') and there means what it says — the row really is absent. So some entity sets DO validate the target. One org and 15 entity sets were swept, so treat neither group as a complete list and read the code that actually came back. Use dataverse_get_attribute_change_history when the question is about one column; it additionally diagnoses which level auditing is switched off at.
NOT EVERY ENTRY IS A RESULT. Dataverse MAY add org-level audit-CONFIGURATION rows (records of auditing itself being switched on or off) to a response. They arrive when an audit-configuration change falls inside the TARGET RECORD'S history window, so their presence and count VARY BY TARGET — a record created after the last such change gets none, while older records on the same org got four each, live-measured. audit_configuration_events_count: 0 is a normal, expected answer. They are identified by their SHAPE — no @odata.type, AuditRecord and nothing else, and an all-zero AuditRecord._objectid_value — never by their position, which is not a contract. They are split out into audit_configuration_events (with audit_configuration_events_count) and are NOT counted: audit_details, count and has_more cover this record's own changes only.
ENTRIES ARE POLYMORPHIC — read each one's @odata.type, and detail_types counts the values present on the returned page. A RECORD-scoped call spans everything that happened to the record, so expect a wider mix than a column-scoped one: AttributeAuditDetail (OldValue/NewValue per changed field), RelationshipAuditDetail, ShareAuditDetail (live-confirmed here), RolePrivilegeAuditDetail and UserAccessAuditDetail are all documented subtypes. Every subtype carries an AuditRecord navigation property (who, when, what operation). An entry with an UNRECOGNIZED @odata.type is reported as a change, never quietly dropped, and unclassified_typeless_count reports how many entries carrying NO @odata.type were kept as changes because they did not match the configuration shape — it is 0 on every response observed so far, and a non-zero value means this tool met an entry it could not name rather than that anything was lost.
RESPONSE SHAPE IS CHECKED, NOT ASSUMED. If the AuditDetailCollection container is absent or is not a list of entries, the tool returns normalized: false with the raw body — a missing container is NOT reported as "no changes".
PagingInfo is not sent, so changes are trimmed client-side to top and has_more reports the server's MoreRecords OR anything the trim cut. total_record_count appears ONLY when Dataverse supplied a real count: it is live-confirmed to arrive as -1 here ("not counted"), and a negative value is suppressed rather than passed on as a number that reads like a count.
URL form: GET /api/data/v9.2/RetrieveRecordChangeHistory(Target=@p1) ?@p1={'@odata.id':'()'}
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description exceeds annotation disclosures with rich behavioral detail: HTTP 200 can mask disabled auditing or nonexistent records, 404 error codes distinguish naming errors from missing rows, entries are polymorphic, configuration rows may appear, response shape is validated, and paging is trimmed client-side. These are critical operational nuances not conveyed by the annotations alone.
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 quite long, but it is well-organized with bolded section headers (e.g., 'HTTP 200 IS NOT PROOF', 'NOT EVERY ENTRY IS A RESULT', 'ENTRIES ARE POLYMORPHIC') that aid navigation. The front-loaded purpose sentence and each subsequent paragraph add substantive value; the length is justified by the tool's complexity, though a bit more editing could make it leaner.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers error handling, edge cases, polymorphic subtypes, configuration rows, response shape validation, and paging semantics comprehensively. Given the tool's complexity and the presence of an output schema, the description goes far beyond what is required, leaving little room for ambiguity.
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?
Despite the schema including descriptions, the tool description adds essential meaning for each parameter: entity_set_name must be the plural OData collection name and should be discovered via dataverse_get_entity_sets, record_id is a GUID, top controls client-side trimming, and dataverse_url is the required org URL. This compensates effectively for the 0% schema description coverage signal.
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 opens with 'Retrieve the full audit change history for a specific record,' a specific verb+resource statement that clearly identifies the tool's function. It also differentiates from the sibling dataverse_get_attribute_change_history by emphasizing record-scoped vs column-scoped history, making the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly directs the agent to use dataverse_get_attribute_change_history for single-column questions, providing a clear alternative. It also advises using dataverse_get_entity_sets when a 404 indicates a naming issue, and warns against interpreting empty responses as evidence of absence, giving concrete when-to and when-not-to guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read the UNPUBLISHED (draft) definition of one customization record.
A normal GET — and therefore dataverse_get_form, dataverse_get_view and dataverse_get_web_resource — returns the PUBLISHED row. Writes such as dataverse_set_formxml, dataverse_add_form_control, dataverse_update_view and dataverse_add_view_column save to the draft, so after any of them the published read is stale until dataverse_publish_customizations runs. Call this tool to read back what you just wrote; reading the published row and then editing it can silently clobber your own unpublished changes.
Supported entity_set_name values: 'savedqueries' (views), 'systemforms' (forms), 'appmodules', 'webresourceset'. Dataverse accepts the RetrieveUnpublished message for only certain customization entity types, and sitemap is NOT one of them — a sitemap draft cannot be read this way, so do not go looking for it. Ordinary data tables such as 'accounts' have no unpublished layer at all.
Returns one record, not a list. By default a small projection is returned with the large XML/binary columns held back (formxml, fetchxml, layoutxml, content) — pass select to ask for them explicitly, e.g. select=['formid','name','formxml']. select is honoured and validated: an unknown column name comes back as an HTTP 400 naming the property.
IMPORTANT — the returned column set is NOT the set you asked for, and it differs in BOTH directions.
FEWER: unlike a plain GET, RetrieveUnpublished omits a requested column whose value is NULL instead of returning it as null. A missing key means "this column is null", NOT "this column does not exist".
MORE: the platform also returns columns you never requested. It is an open-ended set, not one known extra — _organizationid_value comes back on every entity set, and a narrow select on 'systemforms' also returned objecttypecode and type. Treat any unrequested column as possible. So never assume returned set == requested set, and do NOT diff requested against returned to detect a mistyped select column: nulls vanish from that diff and platform extras pollute it. The reliable signal for a bad column name is Dataverse's own HTTP 400 "Could not find a property named ''", surfaced through the error envelope.
If the record has no unpublished changes, the draft and the published row are identical, which is the expected result rather than an error.
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond annotations (readOnlyHint, openWorldHint, idempotentHint), the description discloses critical behaviors: the returned column set is NOT the requested set, NULL-valued columns are omitted, unexpected extra columns like _organizationid_value appear, and invalid column names produce an HTTP 400. It also notes that a record with no changes returns a draft identical to published. This is richly transparent and aligns with the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long but every paragraph earns its place, with a clear first-line definition, bold IMPORTANT warnings, and explicit do/don't guidance. It front-loads the core purpose and then layers specialized details, making it easy for an agent to scan. No redundant fluff or repetition of annotation values.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the full decision context: when to use, expected return shape (one record), select projection caveats, error signaling, and the identity case (no changes). It also names supporting list tools to find record IDs. Given the output schema exists and annotations are present, this description is complete.
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 context reports 0% top-level schema coverage because the only top-level property ('params') lacks a description, but the nested schema (RetrieveUnpublishedInput) provides detailed descriptions for all four real parameters. The tool description adds even more critical nuance about select behavior: default projection excludes large XML/binary columns, NULL columns vanish, and unrequested columns may appear. It also clarifies entity_set_name irregulars and the sitemap limitation, going 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 opens with a specific verb and resource: 'Read the UNPUBLISHED (draft) definition of one customization record.' It distinguishes itself from sibling read tools by explicitly stating that normal GETs and dataverse_get_form/view/web_resource return the PUBLISHED row, while this tool reads the draft. This is a precise purpose statement with clear sibling 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?
Usage is explicitly tied to the write-then-read workflow: 'Call this tool to read back what you just wrote' after describing how write tools save to draft. It also states when NOT to use it: sitemap is not supported, ordinary data tables have no unpublished layer, and reading the published row can 'silently clobber your own unpublished changes.' This is model guidance on when and when-not.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieve all security privileges assigned to a system user via their roles.
Returns RolePrivilege objects with PrivilegeName and Depth. Use dataverse_whoami to get the caller's UserId for checking your own privileges.
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and idempotentHint=true. The description adds that the tool returns RolePrivilege objects with PrivilegeName and Depth, and that privileges come via roles. This provides additional behavioral context beyond the annotations, but does not cover potential side effects or authentication 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 three sentences long, front-loaded with the core purpose, followed by output details and a usage hint. Every sentence adds value with no redundancy or fluff.
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 (implied), the description adequately covers what the tool does, what it returns, and how to obtain the required user ID. It lacks discussion of permission requirements or pagination, but these are minor given the tool's simplicity and the presence of annotations.
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 description does not mention any parameters; however, the input schema provides clear descriptions for both user_id and dataverse_url. Since schema coverage is high (100% for the two parameters), the description adds no extra parameter semantics, earning a baseline score of 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 clearly states the tool retrieves all security privileges assigned to a user via their roles. It specifies the resource and action distinctly from sibling tools like dataverse_get_user or dataverse_audit_user_access. The mention of returning RolePrivilege objects reinforces its purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The tool provides a usage tip to use dataverse_whoami to get the caller's UserId, which guides when to use this tool. However, it does not explicitly exclude alternatives or state prerequisites, leaving some gaps for an AI agent to infer context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Validate a model-driven app and return all errors and warnings.
Uses the ValidateApp function to check for missing required components (sitemap, etc.). An app with validation errors cannot be published. Run this before calling dataverse_publish_app to catch errors early.
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and non-destructive. Description adds that validation errors prevent publishing, which is important behavioral context beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences: first states purpose, second provides additional context and usage. 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 (2 parameters, output schema present), the description fully covers what an agent needs: purpose, implications, and workflow integration.
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 provides descriptions for both parameters (app_id and dataverse_url). Tool description adds no extra parameter details, so baseline 3 is appropriate given schema 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?
Description clearly states it validates a model-driven app and returns errors/warnings, using ValidateApp to check for missing components. Distinct from sibling tools like dataverse_validate_formxml.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly advises running before dataverse_publish_app to catch errors early, providing a clear workflow context. Does not explicitly mention when not to use, but the guidance is sufficient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Check a FetchXML query for problems and performance warnings WITHOUT running it.
Pre-flight companion to dataverse_execute_fetchxml. Calls the unbound ValidateFetchXmlExpression function, which parses and analyses the expression server-side and reports validation errors plus performance suggestions (for example unrestricted column lists or filters that cannot use an index). No records are read and nothing is modified. Run it before executing an expensive or machine-generated query — a FetchXML query that returns results can still be a query that scans a table.
No entity set name is required: the root inside the document identifies the table.
HTTP 200 DOES NOT MEAN THE QUERY IS VALID — check has_errors / error_count. A FetchXml naming a table or attribute that does not exist comes back as a successful HTTP 200 carrying an error-severity message ("Error handling FetchXML: The entity with a name = '...' was not found in the MetadataCache"), not as an HTTP 400. Treating a non-error response as "this query works" is wrong. Read has_errors first, then errors for the error texts.
Findings are reported as: count (total messages), error_count, warning_count (count == error_count + warning_count, so nothing is dropped), has_errors, and errors (the error texts). The severity mapping is OBSERVED, NOT DOCUMENTED: live responses used 1 for performance warnings and 3 for errors, so severity
= 3 is counted as an error and < 3 as a warning. Any message whose severity is missing or not an integer is bucketed conservatively as an error rather than assumed benign, and still appears in count.
The full payload is also returned unchanged under raw_response (minus the @odata envelope): ValidationResults.Helplink, each message's LocalizedMessageText and its OptionalPropertyBag (which carries details such as AttributeCount/AttributeLimit) are worth reading. If the payload is not in the expected ValidationResults.Messages shape it is returned raw with normalized=false and no counts, rather than being guessed at.
The query is checked locally for XML well-formedness first, using a hardened parser that rejects DTDs and entity declarations, so malformed or hostile markup fails immediately with a clear message instead of costing a round trip.
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations (readOnlyHint=true, idempotentHint=true, destructiveHint=false), the description adds critical behavioral traits: HTTP 200 does not imply validity, severity mapping is observed not documented, unknown severities are treated as errors, raw_response is returned unchanged, and the local XML parser rejects DTDs/entities. This exceeds what annotations convey.
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 lengthy but front-loaded with a crisp one-sentence purpose, followed by logically grouped paragraphs covering behavior, output shape, and edge cases. Every paragraph serves a distinct function, though some details (e.g., severity mapping) could be condensed without losing meaning. Overall it is well-structured and information-dense.
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 generously explains the response shape: count, error_count, warning_count, has_errors, errors, raw_response, and the normalized=false fallback. It also covers edge cases like HTTP 414 and non-200 validation errors. For a tool with this complexity and safety-critical validation semantics, the description is fully complete.
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 includes exhaustive descriptions for both fetch_xml and dataverse_url, including encoding constraints and shortening advice. The tool description adds a small contextual note about the root <entity name="..."> identifying the table, but this is also present in the schema. Since schema description coverage effectively handles parameter semantics, the tool description provides marginal added value, matching the baseline 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 opens with 'Check a FetchXML query for problems and performance warnings WITHOUT running it', clearly identifying the verb (check), resource (FetchXML query), and distinguishing it from executing the query. It explicitly names the sibling dataverse_execute_fetchxml as the companion tool, making the tool's unique role unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit usage guidance: 'Run it before executing an expensive or machine-generated query' and names dataverse_execute_fetchxml as the alternative when execution is desired. However, it does not mention when not to use it (e.g., for View XML) or list alternative validators like dataverse_validate_view, so it lacks explicit exclusions but still provides clear context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Validate FormXml against structural rules derived from the FormXml XSD.
Two modes: pass formxml to validate a string directly (dry-run before dataverse_set_formxml), or omit formxml to fetch and validate the live form. Returns valid=true + control list, or valid=false + full error list. All write tools run this validation automatically before every PATCH.
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Adds return value structure (valid=true/false with control list or error list) and notes automatic validation by write tools, complementing annotations (readOnlyHint, idempotentHint) without contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Four sentences front-load purpose and modes, with no wasted words. Each sentence adds value, and structure is logical.
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?
Covers two modes, return values, and automatic validation. With an output schema present, the description is sufficiently complete for this focused validation task.
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?
Description does not directly describe parameters, but the input schema provides detailed descriptions for all three parameters (form_id, formxml, dataverse_url). Tool description adds implicit context for formxml via modes, meeting baseline expectation.
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 validates FormXml against XSD-derived rules, specifying two modes and distinguishing itself from siblings like dataverse_validate_view through the FormXml focus.
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?
Describes two modes (dry-run with formxml, fetch live form without) and mentions automatic validation by write tools, providing clear context for when to use this tool, though no explicit exclusions or alternatives are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Validate a Dataverse view's FetchXml and LayoutXml against 16 structural rules.
Fetches the live XML and checks FetchXml structure (rules 1-8), LayoutXml structure (rules 9-15), and column cross-reference (rule 16). Layout rules are skipped when layoutxml is null. Write tools run this automatically before every PATCH — use this for a standalone pre-check.
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, establishing safety. The description adds behavioral details beyond annotations: it fetches live XML, checks structure according to 16 rules, and skips layout rules when layoutxml is null. No contradictions with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three concise sentences: first states primary action and rule count, second details the rule breakdown, third provides usage context about automatic execution. No redundancy, front-loaded with purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of an output schema (not shown), the description is complete enough for a validation tool with 1 required param and no nested objects. It covers behavior, rule structure, and usage context. Could mention output format briefly, but output schema fills that 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 includes descriptions for both parameters (view_id as GUID, dataverse_url as URL). The description does not add new parameter semantics beyond the schema. With schema descriptions present, baseline is 3; the description adds minimal contextual value (e.g., 'fetches the live XML' linking to view_id).
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 validates a Dataverse view's FetchXml and LayoutXml against 16 structural rules, specifying the rule groups (1-8, 9-15, 16). It distinguishes from sibling tools like dataverse_get_view (retrieval) and other validation tools (dataverse_validate_app, dataverse_validate_formxml) by its specific validation 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?
The description provides clear guidance on when to use this tool: as a standalone pre-check before write operations, noting that write tools automatically run this before every PATCH. It implies when not to use (when doing a PATCH, automatic) but does not explicitly list alternatives among siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return the authenticated caller's identity from the Dataverse WhoAmI endpoint.
Returns UserId, BusinessUnitId, and OrganizationId. Call at session start to confirm authentication and get the caller's UserId for privilege checks.
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Adds context beyond annotations (readOnlyHint, idempotentHint) by specifying the returned fields (UserId, BusinessUnitId, OrganizationId) and the purpose (authentication confirmation). No contradictions.
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 concise sentences that front-load the purpose and include usage guidance. No redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple identity check tool with one parameter and an output schema, the description provides all necessary information: what it does, when to use it, and what it returns. Complete.
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 only parameter (dataverse_url) is already well-described in the input schema. The tool description adds no additional meaning, but schema coverage is adequate, so baseline of 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 'Return the authenticated caller's identity' using a specific verb and resource, and distinguishes itself from siblings like dataverse_get_user by focusing on the current session's identity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly recommends calling 'at session start to confirm authentication' and for privilege checks, providing clear context. Does not mention when not to use or alternatives, but the usage is well-defined.
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.
v3.9.0dataverse_get_attribute_change_historydataverse_get_import_job_resultsdataverse_get_organization_infodataverse_get_role_privilegesdataverse_get_settingdataverse_get_team_privilegesdataverse_get_total_record_countsdataverse_get_valid_relationship_entitiesdataverse_is_component_customizabledataverse_list_languagesdataverse_list_privilegesdataverse_list_shared_principalsdataverse_retrieve_access_origindataverse_retrieve_unpublisheddataverse_validate_fetchxmlv3.6.0dataverse_aggregate_tabledataverse_analyze_dependenciesdataverse_audit_user_accessdataverse_check_relationship_eligibilitydataverse_count_recordsdataverse_execute_batchdataverse_execute_fetchxmldataverse_export_solutiondataverse_get_appdataverse_get_async_operationdataverse_get_audit_detailsdataverse_get_choicedataverse_get_cloud_flowsdataverse_get_columndataverse_get_connection_referencedataverse_get_custom_apidataverse_get_entity_setsdataverse_get_environment_variable_valuesdataverse_get_environment_variablesdataverse_get_formdataverse_get_import_jobdataverse_get_plugin_assemblydataverse_get_plugin_packagedataverse_get_plugin_stepdataverse_get_plugin_step_imagedataverse_get_plugin_trace_log_settingdataverse_get_plugin_typedataverse_get_recorddataverse_get_relationshipdataverse_get_sdk_messagedataverse_get_sdk_message_filterdataverse_get_security_roledataverse_get_solutiondataverse_get_solution_historydataverse_get_table_metadatadataverse_get_teamdataverse_get_userdataverse_get_viewdataverse_get_web_resourcedataverse_list_alternate_keysdataverse_list_appsdataverse_list_async_operationsdataverse_list_auditdataverse_list_business_unitsdataverse_list_choice_column_optionsdataverse_list_choicesdataverse_list_columnsdataverse_list_connection_referencesdataverse_list_custom_api_request_parametersdataverse_list_custom_api_response_propertiesdataverse_list_custom_apisdataverse_list_environmentsdataverse_list_formsdataverse_list_import_jobsdataverse_list_plugin_assembliesdataverse_list_plugin_packagesdataverse_list_plugin_step_imagesdataverse_list_plugin_stepsdataverse_list_plugin_trace_logsdataverse_list_plugin_type_statisticsdataverse_list_plugin_typesdataverse_list_processesdataverse_list_relationshipsdataverse_list_sdk_message_filtersdataverse_list_sdk_messagesdataverse_list_security_rolesdataverse_list_solution_componentsdataverse_list_solution_historiesdataverse_list_solutionsdataverse_list_tablesdataverse_list_teamsdataverse_list_usersdataverse_list_viewsdataverse_list_web_resourcesdataverse_query_tabledataverse_retrieve_principal_accessdataverse_retrieve_record_change_historydataverse_retrieve_user_privilegesdataverse_validate_appdataverse_validate_formxmldataverse_validate_viewdataverse_whoamiThe tool set covers many distinct resources and each tool's description is extremely detailed, often cross-referencing sibling tools (e.g., dataverse_get_import_job vs dataverse_get_import_job_results). A few pairs like dataverse_get_environment_variables and dataverse_get_environment_variable_values could be confused, but the descriptions clarify the difference between definitions and values. Overall, tools are well-differentiated.
All tools follow a dataverse_ prefix with snake_case and generally verb_noun ordering (list_*, get_*, validate_*, etc.). There are minor inconsistencies like using 'get' vs 'retrieve' (get_relationship vs retrieve_unpublished) and singular/plural variance (list_solutions vs get_solution_history), but the pattern is strong and predictable.
With 97 tools, this is far beyond the typical well-scoped range. Even for a comprehensive Dataverse server, the number is extreme, and many tools are narrow inspector endpoints that could be consolidated. It exceeds the 50+ threshold that indicates extreme mismatch.
Despite the large number of tools, the server is almost entirely read-only: it contains no create/update/delete tools for records, tables, columns, relationships, choices, forms, views, web resources, or security roles. Several referenced write tools (dataverse_create_record, dataverse_update_table, etc.) are not actually present in the tool list, leaving agents unable to perform any mutation. This is a severe gap for an administration-focused server.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Debug, build, and manage Power Automate cloud flows with AI agents
Give your AI agents the tools to build, manage, and run automation workflows.
Gateway between LLM agents and world data through eight tools and a bundled endpoint catalog.
Connect AI agents to 1000+ apps with managed authentication and tool-calling.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/ryanmichaeljames/dataverse-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
