Aedifion MCP Server

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It successfully explains processing behaviors like resampling (samplerate), interpolation, aggregation methods, and format options (short). However, it fails to disclose operational traits like read-only safety, rate limits, behavior when datapoints are missing, or data retention 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 follows a logical docstring structure with the high-level purpose front-loaded, followed by an Args block. Given the necessity of documenting 11 parameters with 0% schema coverage, the length is appropriate. Each parameter entry is dense and necessary, though the format could be more narrative rather than docstring-style for MCP contexts.

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 resampling/aggregation logic and an output schema present, the description adequately covers parameter semantics and processing options. However, it omits error handling patterns, relationships between entities (e.g., that datapoints must belong to the specified project_id), and pagination behavior for the 'max' 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?

Given 0% schema description coverage (only titles present), the Args block provides substantial compensation by documenting all 11 parameters with types, formats (e.g., 'ISO 8601', 'comma-separated'), and examples (e.g., '15min', 'linear'). It clarifies that datapoint_ids expects comma-separated hash keys, which the schema only types as 'string'. Minor gap: doesn't indicate required vs. optional parameters in the text.

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 (Get), resource (time series data), and scope (one or more datapoints in a project). It implicitly distinguishes from the sibling `get_datapoint_timeseries` by emphasizing 'one or more' and 'in a project,' signaling batch/aggregate capability versus single-datapoint retrieval, though it could explicitly name the alternative for clarity.

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

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

The description provides no guidance on when to use this tool versus alternatives like `get_datapoint_timeseries` (single vs. multiple datapoints) or `write_project_timeseries`. It lacks prerequisites, error conditions, or exclusion criteria, leaving the agent to infer usage context solely from parameter definitions.

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