tableau-graphql-mcp

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

Annotations already mark it read-only and non-destructive, and the description adds important operational behavior: exact case-sensitive filters, no substring/regex, page size max 1000, an approximate 20,000-node limit, partial_results warnings, and no auto-paging of arbitrary queries. These are substantive details beyond the structured 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 and front-loaded: the purpose and return shape come first, followed by concrete query-writing rules and alternatives. Every section provides useful guidance for a complex GraphQL tool.

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

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

For a complex open-world GraphQL tool, the description covers API scope, query syntax constraints, pagination, result truncation behavior, read-only restrictions, and sibling alternatives. An output schema exists, so return-value explanation is not required.

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

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

Schema description coverage is 0%, so the description must carry parameter meaning. It explains query construction in detail, including filters, pagination, fragments, and entry points, but does not explain the optional variables parameter at all, leaving one parameter 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?

States a specific verb and resource: run ANY read-only GraphQL query against the Tableau Metadata API. It explicitly calls itself the general-purpose tool for lineage questions and distinguishes itself from introspect_schema and lineage_examples.

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

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

Provides explicit usage guidance: use this for any lineage question, call lineage_examples for templates and introspect_schema for schema inspection, and use where_used when Catalog lineage is unavailable. It also states mutation and subscription operations are rejected.

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

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

Beyond the readOnly/openWorld annotations, the description discloses non-obvious traits: `name` is exact and case-sensitive, workbooks are derived from downstream sheets/dashboards because the flat downstreamWorkbooks edge is unreliable, and an empty result on a site without Data Management signals unindexed transitive lineage. These are exactly the operational caveats annotations cannot carry.

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?

Front-loaded with the core capability, then the routing contrast, then operational caveats — a deliberate and useful ordering. It runs slightly long with the parenthetical asides, but every sentence carries distinct information rather than restating the schema.

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

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

Although an output schema exists (so return values need not be explained), the description voluntarily enumerates the return shape (dependent fields, sheets, dashboards, workbooks, de-duplicated owners) and covers the critical failure mode. Nothing an agent needs to invoke or interpret this tool is missing.

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

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

With one parameter at 0% schema description coverage, the description must compensate, and it does: it tells the agent the argument accepts a column, field, or table and must match exactly and case-sensitively. It could still be clearer about naming conventions for non-column targets, but the key semantic is covered.

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?

States a specific verb+resource ('transitive MULTI-HOP downstream impact of a column, field, or table') and immediately distinguishes itself from the sibling `where_used` (one-hop core lineage). An agent can select between the two without opening either schema.

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

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

Gives an explicit use case ('what breaks if I change/drop this?'), names the alternative `where_used` and the exact condition that selects it, plus a documented fallback when the tool returns nothing. Nothing is left to inference.

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

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

Annotations already cover safety (readOnlyHint=true, destructiveHint=false, openWorldHint=true). The description adds real context beyond them: that introspection is enabled on this server, and what each invocation mode returns. It does not discuss error behavior for an invalid type name.

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?

Front-loaded with the action and its scope, then splits cleanly into the no-arg and type_name cases. Every sentence carries information; nothing is 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?

With an output schema present and annotations covering safety, the description only needs to explain modes and the parameter, which it does. The one notable omission is any hint about failure behavior for a nonexistent type name.

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 carry the parameter — and it does, explaining that `type_name` is optional, what happens when omitted, and giving concrete example values ("Column", "Workbook", "DatabaseTable", "CalculatedField"). Case sensitivity and invalid-value handling are left unstated.

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?

Specific verb+resource: "Introspect the live Metadata API GraphQL schema" names exactly what is being inspected and what the two modes yield. It does not name a sibling (e.g. graphql_query) explicitly, so the differentiation is only implicit, which keeps it out of the top band.

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 clearly states the two usage contexts — no argument for entry points/type names, `type_name` for a specific type's fields — and frames the purpose as "so you can write a correct query." It gives no explicit when-not or named alternative, so it stops short of 5.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds value beyond that by disclosing the returned payload's shape (question, graphql, variables, notes) and the optional category filter semantics. It doesn't note rate limits or auth needs, but those are largely irrelevant for a static read tool.

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

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

Front-loaded with the key instruction ('Read this before composing a graphql_query'), then the category list, then filter behavior, then the return shape. Every sentence earns its place and there is 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?

An output schema exists, so return values need not be exhaustively described, yet the description summarizes the example fields. Combined with the enumerated categories and the when-to-use routing, an agent has everything needed to invoke this 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% and the single `category` parameter is a bare string with no enum, so the schema gives an agent nothing. The description compensates fully by enumerating all eight valid values (impact, provenance, calc, datasource, search, inventory, governance, ownership) and explaining default behavior when omitted.

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?

States a specific verb and resource: returns a schema cheat-sheet plus a library of curated lineage questions with their correct GraphQL queries and example variables. This is clearly distinguishable from siblings like graphql_query and introspect_schema, which perform queries rather than supply ready-made examples.

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?

Gives explicit timing guidance tied to a sibling: 'Read this before composing a `graphql_query`.' It also explains the filter behavior ('Pass one to filter; omit to get them all'). However, it never states when not to use it or lists alternative sibling tools for adjacent tasks.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true and destructiveHint=false, so the safety profile is covered. The description adds genuinely new behavioral context beyond them: it searches workbooks, published datasources and tables by default, groups results by type, pages client-side, scans only the first ~1200 of each type, and flags that truncation in a `note` field. Auth/rate-limit details are absent, but the pagination cap is a real 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?

Three tight sentences, front-loaded with the matching semantics before usage routing and the paging caveat. Every clause carries information an agent needs; 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?

With an output schema present, return values need not be explained, and the description still notes grouping and the `note` truncation field. Matching semantics, scope, parameter values, and the paging limit together leave nothing an agent needs to call this 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% and both properties carry only bare titles ('Term', 'Types'), so the description must compensate — and it does. It defines `term` as a case-insensitive substring match on name, and enumerates the `types` values ('workbook', 'datasource', 'table', 'field', 'column') plus the default search scope.

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

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

The description states a specific verb and resource — find content whose NAME contains a substring — and immediately scopes it against siblings by noting that every other tool and the Metadata API filter are exact-match. An agent can distinguish it from graphql_query and where_used without opening a schema.

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

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

It gives explicit when-to-use ('when you only know part of a name') and when-not ('once you know the exact name, prefer graphql_query or where_used'), naming the alternatives. Nothing about tool selection is left to inference.

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

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

Annotations already establish this as a safe, read-only, open-world probe, so the description only needs to add context. It does: it discloses that the call inspects the live connection and even reports whether external-asset (Data Management/Catalog) lineage is available, which tells the agent how much depth to expect from lineage tooling. It omits any note about auth prereqs or failure behavior, keeping it short of a 5.

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 payload of returned fields and followed by the call-ordering advice. The field list is dense but each item is meaningful; there is no filler, though the enumeration is at the edge of being exhaustive for a description.

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

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

With a declared output schema, the description need not spell out return shape, and it doesn't need to — it instead supplies the interpretive layer (which fields matter, what lineage availability implies). For a zero-parameter diagnostic tool this 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 tool takes zero parameters, so per the rubric the baseline is 4. The description correctly implies a no-argument diagnostic call and adds no misleading parameter 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?

Specific verb (report) plus resource (connected Tableau environment), and it enumerates the exact fields returned: server URL, site, product/REST API version, Metadata API endpoint, auth method, and lineage availability. This clearly separates it from the sibling lineage/query tools, which operate on content rather than connection state.

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

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

"Good first call to confirm the connection and understand what lineage depth to expect" gives explicit when-to-use guidance tied to a concrete downstream decision. It does not name an alternative or state exclusions, but the ordering advice is actionable and unambiguous.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds real behavioral context beyond that: it explains the underlying CORE lineage path (referencedByFields -> field.sheets -> workbook) and notes it works even without the Data Management add-on where downstreamWorkbooks is empty, which is non-obvious operational detail.

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

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

Front-loaded with the core answer, then parameters, then mechanism, then alternative routing. The lineage explanation sentence is dense but earns its place by justifying the tool's robustness claim; slightly longer than strictly needed.

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?

An output schema exists, so return values need not be spelled out, and the description still sketches result grouping (by workbook, match type, worksheets) for orientation. Combined with the parameter detail and alternative routing, an agent has what it needs to invoke it correctly.

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

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

Schema coverage is 0%, so the description carries the full burden and does so: `names` are EXACT, case-sensitive, and may be a Snowflake/DB column, a Tableau field or alias, or a database table, with several accepted in one call. This fully specifies input semantics the bare array schema omits.

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?

States a specific verb+resource ('Find which workbooks and published datasources USE the given names') and frames the exact question it answers. It names graphql_query as the escape hatch for other question shapes, but does not differentiate itself from the sibling impact_analysis, which covers an adjacent-sounding 'impact analysis' question.

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 it (the 'where is this used' question), that multiple names can be checked in one call, and redirects other question shapes to graphql_query. No exclusion is drawn against impact_analysis, so the routing advice is clear but not exhaustive.

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