list_data_sources

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 the scanning mechanism and the return content, namely distinct connections plus which queries use them. It does not discuss permissions, performance, or connector-detection limits, but the read-only inventory nature is reasonably clear from the text.

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 action and mechanism, then follows with practical scenarios. It is longer than necessary in places, especially the example list, but no sentence is pure filler. Overall it remains readable and focused.

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 has an output schema, so the description need not detail return values, and it already explains enough about output shape. But the required 'instance' parameter is undocumented in both schema and description, and there are no annotations to cover safety or behavior. It is adequate for purpose but incomplete for 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?

The only parameter is required and named 'instance', but the description never explains what an instance is, what format it expects, or how to obtain it. Schema description coverage is 0%, so the description needed to compensate and does not. This is a meaningful gap for the single required input.

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: inventory every data source the model connects to. It explains the mechanism, scanning table and shared query M code for connector function calls, which distinguishes it from simpler listing tools. An agent can tell what this tool does 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?

It gives concrete usage scenarios such as spotting a dev/test server in production or confirming expected data sources. However, it does not explicitly say when not to use it or name alternatives such as classify_connections or analyze_sharepoint_patterns. The context is clear but lacks exclusion guidance.

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