ms-fabric-mcp-server

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

Since no annotations are provided, the description carries the full burden of behavioral disclosure. It effectively describes the tool's behavior: retrieving an existing pipeline, adding a Dataflow Activity, updating the pipeline definition, and appending to existing activities. It also mentions default values for parameters like timeout and retry settings. However, it doesn't cover potential side effects, error conditions, 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 well-structured with clear sections: purpose statement, behavioral explanation, usage guidelines, parameter details, and return values. Every sentence adds value - the first paragraph explains what the tool does, the bullet points provide usage context, and the parameter section adds crucial information missing 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?

Given the complexity of a 9-parameter mutation tool with no annotations and 0% schema description coverage, the description provides comprehensive coverage. It explains the tool's purpose, when to use it, detailed parameter semantics, and includes return value information. With an output schema present, the description appropriately focuses on the tool's behavior and inputs rather than output details.

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 fully compensates by providing detailed explanations for all 9 parameters. It clarifies optional vs. required parameters, explains what each parameter represents (e.g., 'display name of the workspace,' 'name of the existing pipeline'), and provides default values for optional parameters like timeout and retry settings.

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 ('Add a Dataflow Activity to an existing Fabric pipeline') and distinguishes it from sibling tools like 'add_copy_activity_to_pipeline' and 'add_notebook_activity_to_pipeline' by specifying it's for Dataflow Activities. It explicitly mentions the resource ('existing Fabric pipeline') and the verb ('add').

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 includes an explicit 'Use this tool when:' section with three bullet points that clearly define the appropriate contexts for using this tool, such as when you have an existing pipeline, are building complex pipelines, or want incremental pipeline building. This provides clear guidance on when to select this tool over alternatives.

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