analyze_sharepoint_patterns

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

With no annotations at all, the description carries the full disclosure burden. It does add real behavioral insight — notably that swallowed `try ... otherwise null/false` errors let refreshes succeed with missing data, and that SharePoint.Files enumerates the whole site before filtering — but says nothing about read-only vs. mutating behavior, required access to the model/mashup, or cost of the scan.

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?

Information-dense with no filler, and the topic is front-loaded. However it is a single comma-spliced run-on list of a dozen checks, which makes it harder to scan than a short purpose sentence followed by grouped bullets.

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 needn't be explained. But for a two-parameter analysis tool with zero annotation coverage, leaving the required `instance` argument undefined and not stating whether this is a safe read-only inspection is a 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 coverage is 0% for both parameters. The description never explains the required `instance` parameter (which instance — model, workspace, site?), and `include_row_counts` is only obliquely hinted at by 'queries that never reduce columns or rows.' The most important parameter is left 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?

The opening phrase 'SharePoint loading review' plus the enumerated anti-patterns makes it clear this is an audit of SharePoint-oriented Power Query loading patterns, distinguishing it from siblings like analyze_sql_queries or analyze_folding_risk. It never states plainly that it returns findings/report, so it reads as a topic list rather than a described action.

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 SharePoint framing implies the use case (models pulling data from SharePoint lists/files), but there is no explicit when-to-use, no prerequisites, and no named alternative among the many analyze_*/diagnose_* siblings. Usage is inferable only from subject matter.

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