Tableau Knowledge MCP

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

Annotations already cover the read-only, non-destructive, open-world profile, and the description adds substantial context beyond them: concrete limits (50 rules / 8,000 chars on Cloud, 30,000 on Next), the failure mode where a malformed line is silently ignored, and the return shape (`ok`, `issues` by line, stats). It never contradicts 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?

Purpose and the first-call instruction are front-loaded, and the check inventory is dense rather than padded. The long enumerated "Checks:" sentence is justified by the tool's breadth but is heavy to parse in one pass.

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 complex validator: it explains what is checked, the per-product limits, the optional target-based field validation, and what comes back, and an output schema exists so return details are partly redundant anyway. The unexplained `graph_id` is the one gap an agent could stumble on.

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 load, and it does for three of four params: `text` as the rule file content, `target` as a dashboard/sheet/workbook/data source id or description that triggers field-caption validation with "did you mean" hints, and `product` as "cloud" or "next" with different limits. `graph_id` is never mentioned, leaving one parameter undocumented in both schema and description.

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

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

States a precise verb+resource: validating a Tableau Business Preferences file of "# rule" lines so the agent actually follows each one. It also names the domain objects it inspects (rules, headers, thresholds, [Field] references) and is clearly distinct from the graph/lineage 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?

Explicitly prescribes the first call ("Call it with no `text` first to get the rulebook") and explains what `target` and `product` add on subsequent calls. It gives strong in-workflow guidance but does not state when not to use it or point to any alternative, which is less critical here since no sibling overlaps.

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 cover the safety profile (not read-only, non-idempotent, non-destructive), and the description adds what they cannot: the Creator role requirement, the statement length bounds (5-1000 chars), the target-node type restrictions, the specific API error and its workaround, and the return shape ("Returns the new context, with its id"). No contradiction with the declared hints.

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 WRITE marker, then the mutual-exclusion rule, then the edge cases and permission note — every sentence carries information. The third block packs target restrictions, an error code, and a workaround into one dense passage, which slightly hurts scanability but not correctness.

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 detailed, yet the description still notes the returned id. The one genuine hole is graph_id: with is_global and target_node_id both explained, an agent has no idea when graph_id is required or how it interacts with the other two.

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 load, and it does for four of five parameters: statements (with size bounds and an example), target_node_id (with sourcing guidance from search_nodes/get_node), is_global (whole-graph scope), and name (optional, auto-derived). graph_id is never mentioned, leaving one parameter with no explanation anywhere.

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?

Opens with an explicit verb+resource+mode marker ("WRITE: attach business context ... to the knowledge graph") and gives a concrete example statement, so the effect is unambiguous. It is clearly distinguishable from its update_semantic_context / delete_semantic_context / search_semantic_contexts 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?

States the exclusivity rule outright ("Set exactly ONE of: target_node_id ... or is_global=true"), enumerates the node types that cannot be targets, and provides a concrete fallback path when the API rejects site-scoped context (error node_semantic_context_disabled). This is explicit when/when-not guidance with an error-driven alternative.

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?

Adds substantial behavior beyond the annotations: requires the Creator role, ignores non-semantic node ids, refuses Tableau-managed contexts, succeeds without effect for nonexistent ids, and returns deleted name/statements for possible recreation. These details are consistent with destructiveHint=true, idempotentHint=true, and readOnlyHint=false.

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 'WRITE', then moves efficiently through eligibility, return behavior, edge cases, and authorization. Every sentence adds operational value with no 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 destructive write tool, the description supplies the critical safety, authorization, eligibility, and idempotency context, while annotations and an output schema cover safety signals and return shape. The remaining gap is parameter-level detail, especially graph_id, which the schema also lacks.

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

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

Schema description coverage is 0%, but the description does not explain the parameters. It refers generically to 'ids' and deleting an 'id', but never maps behavior to ctx_id or clarifies the optional graph_id at all, leaving both parameters semantically 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 write action and resource: delete a user-managed semantic context and its statements. It also scopes the operation by distinguishing user-created Tableau Knowledge contexts from Tableau-managed and non-context node ids, so an agent can identify the correct operation without opening the 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 clear when/when-not guidance: only contexts created through Tableau Knowledge can be deleted, other node ids are ignored, and Tableau-managed SEMANTIC_CONTEXT_EXTERNAL contexts are refused. It does not name sibling alternatives such as update_semantic_context, but the eligibility rules are explicit.

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 cover the safety profile (readOnly, non-destructive, open-world), and the description adds real behavioral context: exactly how tables/fields/calcs map to Ossie constructs, when portable SQL is emitted, and the caveat that Tableau Knowledge carries no physical table paths or join keys so `source`/`relationships` need manual completion. It does not state size limits or performance characteristics, but the transformation contract is well disclosed.

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

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

Purpose and return shape are front-loaded in the first sentence, followed by mapping details and warnings in descending priority. Dense but nearly every clause carries decision-relevant information; the parenthetical examples aid rather than pad.

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 the return-value recap is bonus rather than necessary, and the loss/precondition warnings are strong. However, for a 4-parameter tool with zero schema description coverage, the silence on `graph_id` and especially `include_hidden` (which changes what is exported) is a meaningful gap in a description that otherwise sets a high bar.

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

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

Schema description coverage is 0%, so the description must compensate. It explains `datasource` (PDS id or a description of it) and `default_aggregation_metrics` (turn each measure's default aggregation into a metric), but leaves `graph_id` and `include_hidden` entirely undocumented, leaving half the parameters opaque.

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—export a published data source's semantic model to Apache Ossie YAML—and defines the target format in vendor-neutral terms. The export direction cleanly distinguishes it from import_from_ossie, validate_ossie, and ossie_guide without opening any 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?

Says where the `datasource` id comes from (list_sources) and points to ossie_guide for background, and instructs the agent to always read `losses` before using the output. It lacks an explicit statement of when to prefer validate_ossie or import_from_ossie instead, but the usage context is clear.

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?

The annotations already establish that this is a read-only, non-destructive, open-world operation. The description adds meaningful behavior beyond that: plain-language node inputs trigger semantic resolution with match scores and alternatives, and include_children=false skips connected_nodes for large containers.

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 and front-loaded, with the core purpose in the first sentence and parameter behavior clarified in the second paragraph. Every sentence adds useful information without repetition.

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

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

The description is sufficient for basic retrieval and explains the semantic-resolution behavior, but it leaves graph_id undocumented and does not clarify routing versus search_nodes. Given the 0% schema description coverage, those are meaningful gaps for an agent deciding how to scope or select the call.

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 node (id or plain-language query with resolution details) and include_children (skips connected_nodes), but graph_id is completely 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 uses a specific verb and resource, 'Get one node', and enumerates what is returned: properties, semantic statements, and connected_nodes with edge types. It is clear, but it does not explicitly distinguish this retrieval tool from the sibling search_nodes 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?

It gives useful conditional guidance for include_children=false on large containers and explains that node can be a plain-language query resolved by semantic search. However, it never states when to use get_node instead of search_nodes, list_edges, or other sibling tools.

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?

The description adds substantial behavioral detail beyond the readOnly/non-destructive annotations: it defines the 0-100 score, explains that filters apply only to suggestion lists while score/metrics cover the full graph, and notes the default limit against a busy graph with hundreds of suggestions. These are non-obvious semantics that prevent misinterpretation of 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?

Two tight paragraphs, front-loaded with what the tool returns and followed by scoping/filter semantics. Every sentence adds distinct information; nothing is repeated from the schema or annotations.

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 thorough about output structure and filter behavior, and the presence of an output schema reduces the need to explain return values further. The missing explanation of graph_id and its relationship to pds_id is the only notable gap for a five-parameter tool.

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

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

With 0% schema description coverage, the description carries the full burden and explains four of five parameters: pds_id scoping, severity allowed values, suggestion_type filtering, and limit default/scale. graph_id is completely undocumented, leaving one parameter's purpose and interaction with pds_id undefined.

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 names a specific report resource and enumerates its contents (health_score, coverage metrics, graph stats, suggestions), making it unmistakable what the tool returns. No sibling tool produces a health report, so the distinction is inherent even without an explicit comparison.

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 report context is clear enough that an agent knows to use this tool when assessing graph health, and the second paragraph gives explicit guidance on how scoping and filtering work. It stops short of naming alternatives or stating when not to use it, but for a unique health-report endpoint no alternative exists.

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 readOnly/openWorld/non-destructive, so the bar is lower, and the description adds real value beyond them: traversal edge type (DEPENDS_ON), a depth cap of 10 steps, and the fact that the queried node is excluded from results. It does not say what happens when the depth cap truncates a larger blast radius, which is the one behavioral detail an agent would want.

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 short blocks: the purpose/scope lead, the input note, then the return keys. Every sentence carries information (scope, depth limit, edge type, self-exclusion, return shape) with no filler, and the highest-value content 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?

An output schema exists, so the brief mention of `total`, `counts_by_type`, and sorted `affected_assets` is sufficient rather than redundant. For a two-parameter read tool with annotations, the only real omission is the undefined `graph_id` and truncation behavior at the 10-step limit.

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 does well for `node` (accepts a node id OR a plain-language description, a non-obvious flexibility), but `graph_id` is never mentioned at all, leaving the second parameter entirely unexplained.

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

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

Opens with a concrete verb-in-context question ('What breaks if this changes') and precisely defines the resource: every asset depending on the node, direct or transitive, up to 10 steps along DEPENDS_ON. The examples (calcs, sheets, dashboards, workbooks downstream of a column) and the explicit exclusion of the node itself leave no ambiguity about what the tool returns versus a generic traversal.

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 'what breaks if this changes' framing gives a clear use context, and the DEPENDS_ON/10-step scope implies when a broader traversal (e.g. the `lineage` sibling) would be the alternative. However, it never names an alternative or states a when-not-to-use condition, so the agent must infer the boundary with `lineage` itself.

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?

Adds substantial context beyond annotations: dry-run default, the `node_semantic_context_disabled` fallback path, and explicit confirmation that re-import updates rather than duplicates contexts (supporting idempotentHint). It does not spell out what happens to existing context statements that the new model no longer contains — a gap for a tool flagged destructiveHint=true.

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-loads purpose and the read/write gate before the detail, and each paragraph maps to a decision the agent must make. It is on the long side and the `scope` sentence is dense, but 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?

For a 7-parameter, destructive, open-world import with an output schema, the description covers the mutation gate, matching strategy, fallback behavior, permissions, and the human-approval loop. Return-value detail can be deferred to 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?

With 0% schema description coverage the description carries the load, and it explains `document` (YAML or JSON text), `apply` (write gate), `scope` with all three values and their fallback behavior, `target_datasource_id` (exact PDS id from list_sources), and `include_definitions`; `model_name` is only implicitly covered via the `ossie:<model>` naming and `graph_id` is never mentioned.

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: importing an Apache Ossie model's business meaning into Tableau Knowledge as semantic contexts. The inverse relationship to `export_to_ossie` and the contrast with `validate_ossie`/`ossie_guide` are clear enough that an agent can pick this tool without opening sibling schemas.

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 two-step workflow (call dry to get the PLAN, show create/update/unchanged and `unmatched`, then re-call with `apply=true` after user agreement), plus the prerequisite (Creator role) and the conditional requirement for `target_datasource_id` when the model wasn't exported by `export_to_ossie`.

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 read-only/open-world safety, and the description adds genuinely new behavioral detail: a hard 10-step traversal cap, which edge types are followed, which are not (containment), and the resulting edge case for single fields. It also sketches the return payload (anchor, nodes, edges with source_id -> target_id and type, counts), which goes beyond what the 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?

Front-loaded with the core purpose, then edge-type scope, then containment caveat, then return shape and alternative. Every sentence adds information; the example ('a data source and the workbooks built on it') and the two quoted questions efficiently anchor usage.

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 not be fully explained, and the description still summarizes them. Traversal semantics, limits, and alternatives are all covered. The main gap is the undocumented `graph_id` parameter and whether it scopes the traversal to a particular graph.

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 carries the burden. It clarifies that `node` accepts either a node id or a plain-language description, which is valuable, but the second parameter `graph_id` (nullable, default null) is never mentioned, leaving half the parameters 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 resource and traversal scope ('lineage neighborhood of a node: every node reachable within 10 steps, upstream AND downstream, along lineage/dependency edges') and names the edge types followed. This is clearly distinguishable from siblings like impact_analysis, list_edges, and get_node.

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 questions it answers ('where does this come from?', 'what uses it?'), states the exclusion (containment edges not followed, with the consequence that a single field returns only itself), and redirects to list_edges/get_node for containment and to impact_analysis for 'what breaks if this changes?'.

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 readOnly/openWorld/non-destructive, so the safety profile is covered; the description adds genuinely new behavior — one-hop boundary, direction semantics, and default "omit for both." It does not cover edge cases such as an unresolvable or ambiguous plain-language node, which matters for a mutation-free but fuzzy lookup.

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?

Purpose and scope lead, then a compact parameter paragraph — no filler. Every clause either bounds the behavior (one hop) or routes to a sibling (lineage), and the edge-type enumeration is terse yet complete.

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 no explanation, and the description covers scope, the sibling alternative, and three of four parameters. The `graph_id` parameter is never mentioned, so an agent omitting it must infer that a default graph applies.

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

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

Schema coverage is 0% and no enums are declared, so the description carries the burden — and it does: it explains `node` accepts an id or plain-language description, enumerates all seven valid `edge_type` values, and gives the two `direction` values plus the omit-for-both default. Only `graph_id` is left undocumented, which keeps it short of a 5.

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 and resource ("List the edges around one node") with the return shape and scope stated up front ("each with its direction ... and the node on the other end"). The closing clause "One hop only; use lineage for the wider neighborhood" distinguishes it from the `lineage` sibling without requiring a schema read.

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?

Names the alternative (`lineage`) and the condition that selects it (wider neighborhood), which is the key routing decision for this tool. It gives no guidance on prerequisites or when neither tool applies (e.g. vs. `search_nodes`/`get_node`), so it 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.

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile needs no restating. The description adds useful framing that the results are the provenance of the graph, but says nothing about ordering, volume, or what an empty graph returns. With annotations carrying the risk profile, this is adequate but thin.

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

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

Two sentences, zero waste, and the core purpose is front-loaded with the filtering detail after it. The backticked literal values make the parameter guidance scannable at a glance.

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, annotations cover safety, and an output schema exists so return values need no explanation. The one real gap is graph_id — an agent cannot tell from the description what happens if it is omitted or whether it is required in practice.

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 burden, and it does explain node_type's accepted values ("PDS" or "WORKBOOK") and the omitted-means-both default — information the schema lacks since no enum is declared. However, graph_id is never mentioned, leaving half the parameters undocumented in both places.

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 the published data sources and workbooks") and adds a scoping gloss ("what the graph has been built from") that tells an agent this is inventory, not traversal. It does not name any sibling such as lineage or search_nodes, so the differentiation from the closest alternatives is left implicit.

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 only guidance is parameter-level: use node_type to narrow, omit for both. There is no statement of when to reach for list_sources versus lineage, search_nodes, or graph_health, even though those siblings sit adjacent to the same graph-inventory concept. Usage is implied by the phrasing rather than stated.

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=false, and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context by explaining that `topic` selects a section and omitting it returns everything, though it does not describe the output format or size.

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 ends with actionable topic/usage guidance. It is slightly repetitive because the covered topics are listed once in prose and again as the `topic` enum, but the repetition is helpful rather than wasteful.

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, annotations, and single optional parameter, the description provides everything an agent needs: what the tool is, when to use it, valid topic values, and default behavior. No important gap remains for correct invocation.

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

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

Schema description coverage is 0% and the schema has no enum, so the description carries the full burden. It compensates completely by enumerating every valid `topic` value and explicitly stating that omitting the parameter returns all topics.

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 resource and scope: reference documentation for Apache Ossie semantic models, covering versions, object model, expressions, Tableau mapping, converters, and porting. It is clearly distinguishable from sibling operational tools such as export_to_ossie, validate_ossie, and import_from_ossie because it is explicitly a reference/read-before-editing guide.

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 a clear triggering condition: read it before hand-editing a model or advising on a port. It does not name explicit alternatives or when-not-to-use scenarios, but for a documentation tool the guidance is strong enough that an agent knows when to reach for it.

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 the read-only, non-destructive, open-world profile, so the description is not burdened with safety disclosure. It adds genuine value beyond that: ranked 0-1 scores, the semantic_statements field when a statement matched, and the threshold/limit filtering behavior. What remains unstated is pagination beyond limit and any latency or cost 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?

Front-loaded with the core distinction (meaning, not exact name) before the reference detail. The bulleted parameter notes are dense and every sentence earns its place; nothing is padded or repeated from 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?

An output schema exists, yet the description still usefully flags the score field and semantic_statements, which are the fields an agent will actually act on. Combined with the tool-selection guidance and chaining advice, this is nearly complete for a search tool, with graph_id being the only meaningful omission.

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 load, and it does for four of six parameters: node_type (with the full valid value list), scope_id (with the PDS subtree semantics), limit range and default, and threshold semantics. query is self-evident, but graph_id is never mentioned in either the description or the schema, leaving one parameter fully opaque.

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 ('Find graph nodes') and immediately disambiguates the mechanism: semantic matching rather than exact-name lookup, with a concrete example ('revenue' matching 'Net Sales'). An agent can distinguish this from sibling tools like get_node or search_semantic_contexts without opening the 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?

Explains when to use it (finding nodes by meaning) and names the downstream siblings to chain into (get_node, list_edges, lineage, impact_analysis). It stops short of explicitly naming an alternative for exact-name lookup or stating when not to use this tool, so it is strong but not fully prescriptive.

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 the safety profile (readOnlyHint=true, destructiveHint=false, openWorldHint=true), and the description adds real context on top: it distinguishes editable user-managed contexts from read-only Tableau-managed ones, and discloses an API limitation ('doesn't filter by text yet'). It stops short of describing result ordering or volume, but with an output schema present that is a minor omission.

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 definition, then two scannable bullets for the two filtering modes, then the alternative-tool note. No filler sentences; every clause conveys a distinct rule the agent needs.

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 three-optional-parameter list tool with annotations and an output schema, this is nearly complete — filtering behavior and result mutability are both covered. The only gap is the unexplained `graph_id` parameter, which matters for an agent operating across multiple graphs.

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 carries the burden. It fully explains `node` (accepts an id or a description) and `is_global` (true/false/omitted semantics), but `graph_id` is never mentioned in the description or the schema, leaving one of three parameters 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 ('List semantic contexts') and immediately defines what a semantic context actually is (definitions, rules, caveats attached to the graph). The closing line explicitly routes text-meaning lookups to the sibling search_nodes, so an agent can separate it from the other search tools 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?

Gives explicit when-to-use branches: with `node` scopes to that node's contexts, without `node` returns everything with `is_global` narrowing to graph-wide vs node-attached. It also names the alternative (search_nodes) for the case this tool cannot serve, which is exactly the exclusion guidance the dimension asks for.

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, openWorldHint=true, so the safety profile is covered. The description adds useful context that this is a connection-confirmation step and that graph_id defaults to the primary graph, but says nothing about latency, permissions required, or failure behavior if the connection is broken.

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 purpose, then the field list, then the actionable 'Good first call' guidance in priority order. Every clause carries information; 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 zero parameters and an output schema already covering the return shape, the description only needs to say what the call is for and why an agent should make it. Both are answered, plus the graph_id handoff detail that makes downstream calls correct.

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 the baseline of 4 applies; the schema cannot be missing anything. The graph_id note refers to sibling tools' arguments rather than this tool's own input, so it adds cross-tool clarity but no local parameter detail.

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?

Names a specific verb and resource ('Report the connected Tableau site and its knowledge graphs') and enumerates the returned fields (server URL, site, product version, auth method, availability flag, and per-graph id/name/status/is_primary). An agent can distinguish it from siblings like graph_health or search_nodes without opening any 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?

Explicitly frames itself as a 'Good first call' and explains how its output feeds other tools ('gives the graph ids the other tools accept as graph_id'), including the default when graph_id is omitted. No when-not conditions or named alternative diagnostics (e.g., graph_health) are given, so it falls short of a 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 flag destructiveHint=true and idempotentHint=true, and the description adds the crucial nuance that `statements` REPLACES the entire stored set rather than appending — the single most important behavioral fact for this tool. It also discloses the auth prerequisite (Creator role) and the hard exclusion on external contexts, which annotations cannot express.

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 WRITE marker, then a bulleted per-parameter breakdown that scans quickly. Every line carries a distinct constraint or side effect; nothing is redundant 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 destructive, idempotent mutation with an output schema (so return values need no explanation), the description covers side effects, permissions, and invalid targets well. The only real gap is the unexplained `graph_id` parameter, which an agent must guess at or read from the schema title alone.

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

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

Schema coverage is 0%, so the description carries the full burden and mostly delivers: it explains `name` (rename), `statements` (full replacement), `attach_to` (exact node id), `make_global` (detach + graph-wide), and the mutual exclusion between the last two. `graph_id` is never mentioned, leaving one of six parameters undocumented in both schema and description.

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

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

Opens with an explicit verb and resource ("WRITE: change a user-managed semantic context") and names the identifier form (`ctx_id`, e.g. "semctx:<uuid>"), so it is immediately distinguishable from create_semantic_context and delete_semantic_context siblings. The qualifier "user-managed" further scopes what kind of object this acts on.

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 strong when/when-not guidance: Tableau-managed (SEMANTIC_CONTEXT_EXTERNAL) contexts can't be changed, the Creator role is required, and attach_to vs make_global are mutually exclusive ("Not both"). It never names a sibling alternative for the excluded cases, so it stops just short of a 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 description needn't restate safety, but it adds real context: the bundled schema version, automatic 0.1.1→0.2.0 conversion, and the explicit note that execution is local with nothing sent to Tableau. The enumerated semantic checks further disclose what failure modes to expect. It stops short of describing error/report shape, but an output schema exists for that.

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 verb and resource, then the validation targets, then the conversion caveat, then the locality note — a sensible ordering with little waste. The mid-sentence list of semantic rules is dense but each item is informative rather than 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, return values needn't be explained, and both parameters plus the version-conversion edge case are covered. For a two-parameter read-only validator, an agent has everything needed to call 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 description coverage is 0%, so the description carries the burden and largely does: `document` is identified as YAML or JSON text, and `model_name` is explained as the disambiguator for 0.1.1 documents holding several models. It doesn't clarify `model_name` behavior for 0.2.0 documents or what happens when it's omitted/ambiguous, which is the remaining 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?

States a specific verb (validate) and resource (Apache Ossie model given as YAML/JSON text), plus the exact standard it checks against (bundled JSON Schema 0.2.0.dev0 and spec semantic rules). This is clearly distinguishable from the sibling import/export tools, which move data rather than check it.

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 implied rather than stated: the agent can infer this is a pre-flight check for Ossie documents, and the description gives a conditional rule for `model_name` on multi-model 0.1.1 documents. However, it never names an alternative or says when not to use it (e.g., versus import_from_ossie, which presumably also parses documents), leaving routing to inference.

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