list_tables

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

Annotations already provide readOnlyHint=true and openWorldHint=true, covering the read-only nature. The description adds meaningful context: it mentions FetchXML usage, the lack of live column metadata in pac, and the dependency of describe_table on a source. No contradictions with annotations. It doesn't discuss limits or pagination, but that is a minor gap given the annotations.

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 reasonably concise, front-loading the core purpose and then elaborating on the two modes and the pattern filter. It could be slightly more compact but avoids unnecessary fluff and is well-structured for an agent to parse.

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 six parameters, no output schema, and zero schema descriptions, the description covers the essential mode distinction and the pattern parameter but fails to explain the remaining parameters. An agent might invoke it correctly for basic usage, but the lack of detail on limit, custom_only, app, and environment creates ambiguity. The description is helpful but not fully complete.

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 description coverage is 0%, so the description carries the burden. It clarifies 'source' (solution zip/folder or canvas .msapp/SourceCode folder) and 'pattern' (substring on logical or display name). However, it leaves 'app', 'limit', 'custom_only', and 'environment' unexplained, forcing the agent to infer their meanings from names and defaults.

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 verb 'list' and resource 'Dataverse tables', and precisely distinguishes two modes (with/without source) and what each returns. It explicitly mentions the pattern filter and differentiates from describe_table by noting it needs a source, making the tool's purpose unmistakable.

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 implies when to use this tool: with source for cached app tables and without source for live environment names. It also hints that describe_table is needed for column metadata, but does not explicitly enumerate alternatives or exclusions for other siblings. The guidance is clear enough for basic selection.

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