Skip to main content
Glama
web-algebra-mcp

web-algebra-mcp

Official
by AtomGraph

ldh-AddResultSetChart

Creates a chart resource from an existing SPARQL SELECT query in a LinkedDataHub document, mapping category and series variables for table, bar, line, scatter, or timeline visualizations.

Instructions

Writes a chart of SPARQL SELECT query results to a LinkedDataHub document. The chart is a resource the document holds, not one of its content blocks: to show it in the content mode, place it with ldh-AddObjectBlock, the chart's URI as its value - so give the chart a fragment identifier.

    A chart shows values: the query's bindings themselves, as a table or a plot, the way a spreadsheet would.
    It is the fit for aggregates and measurements - totals, counts, sums per shop or per month. A resource in
    a chart is a bare cell, with no image, label or links of its own: to show resources themselves (things,
    people, places), use ldh-AddView, whose modes render each one as itself.

    A query that returns a row per resource, with the resource's URI among its variables, is a list of
    resources and belongs in a view, however many values from related resources it joins in (a thing with
    its shop, price and date of purchase; a message with its sender). A chart of it shows each resource as
    its address. Chart only what is not one row per resource: totals, counts, sums by shop or by month.
    
    This tool:
    - Creates an ldh:ResultSetChart resource linked to an existing sp:Select query resource
    - Configures chart type and variable mappings for visualization
    - Posts the new chart resource to the target document
    - Supports optional title, description, and fragment identifier
    
    Possible chart types include:
    - https://w3id.org/atomgraph/client#Table: Table visualization of results
    - https://w3id.org/atomgraph/client#BarChart: Bar chart visualization
    - https://w3id.org/atomgraph/client#LineChart: Line chart visualization
    - https://w3id.org/atomgraph/client#ScatterChart: Scatter chart visualization
    - https://w3id.org/atomgraph/client#Timeline: Timeline visualization

    Note: The query parameter must be a URI of an existing sp:Select resource, not a SPARQL query string.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "url": "<url>",
      "query": "<query>",
      "title": "<title>",
      "chart_type": "<chart_type>",
      "category_var_name": "<category_var_name>",
      "series_var_name": "<series_var_name>"
    },
    "name": "ldh-AddResultSetChart"
  }
}

Input Schema

NameRequiredDescriptionDefault
urlYesThe URI of the document to write the chart to.
queryYesURI of an existing sp:Select query resource to visualize (not a SPARQL query string).
titleYesTitle of the chart.
fragmentNoOptional fragment identifier for the chart URI (e.g., 'my-chart' creates #my-chart).
chart_typeYesURI of the chart type (e.g., https://w3id.org/atomgraph/client#BarChart).
descriptionNoOptional description of the chart.
series_var_nameYesName of the SPARQL variable used as series/value (without leading '?'), or an array of names for several series.
category_var_nameYesName of the SPARQL variable used as category (without leading '?').

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv2.0.4

TDQS

A4.4/5.0
Behavior4/5

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

With no annotations, the description carries the burden and does well: it discloses that the chart becomes a resource held by the document rather than a content block, that placement requires ldh-AddObjectBlock plus a fragment identifier, and that the query must reference an existing sp:Select resource rather than a query string. It omits permission/auth requirements and what the call returns (URI of the new chart, failure modes), which is the remaining gap for a mutation tool.

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

Conciseness3/5

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

The core routing guidance is front-loaded, but the resource-vs-value distinction is made twice in overlapping paragraphs, and the bulleted 'This tool:' list largely restates the opening sentence and the chart-type list. Trimming those would lose no decision-relevant information.

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

Completeness4/5

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

For an 8-parameter mutation tool with no annotations and no output schema, the definition covers purpose, routing, follow-up placement, and the enum of chart types thoroughly. It stops short of stating authorization expectations or the result of the call, which an agent would still want before invoking it.

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

Parameters4/5

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

Schema coverage is 100%, so baseline would be 3; the description earns more by explaining the chart types with human-readable labels, emphasizing that 'query' is a resource URI not a SPARQL string, and explaining why 'fragment' matters (it enables placement via ldh-AddObjectBlock). It adds little on the category/series variable mapping beyond what the schema already says.

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

Purpose5/5

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

Opens with a precise verb and resource: 'Writes a chart of SPARQL SELECT query results to a LinkedDataHub document.' It further pins down what the output object is (an ldh:ResultSetChart linked to an existing sp:Select query) and explicitly distinguishes it from ldh-AddView and ldh-AddObjectBlock, so an agent can choose without opening schemas.

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

Usage Guidelines5/5

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

Gives explicit when-to-use (aggregates, totals, counts, sums per shop or month) and when-not-to-use (one row per resource, resource URIs among variables, anything showing resources as themselves), naming ldh-AddView as the alternative and ldh-AddObjectBlock as the follow-up placement step. Exclusions and alternatives are both stated concretely.

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