list_form_fields

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

Since no annotations are provided, the description carries the transparency burden and does a good job by disclosing the scope of the operation and the data categories returned: legacy fields with name/value/options, and content controls with tag/alias and placeholder state. It does not explicitly state 'read-only', but the verb 'list' and the output-focused wording make the non-mutating nature clear.

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?

One compact, well-organized sentence front-loads the core purpose and then efficiently enumerates the field categories and their attributes. Every clause adds useful information and there is no filler.

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 description is complete for a listing tool with one simple parameter: it states the full scope, the form field types covered, and that tables are included. The output schema is present, so return-value details are not the description's responsibility, though the undocumented file_path parameter is a minor gap.

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 schema has a single required parameter file_path with 0% description coverage, and the tool description never mentions this parameter. The parameter name is somewhat self-explanatory, but the description adds no explicit meaning about what kind of path is expected or how it should be supplied.

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 precisely identifies the resource: every fillable form field in the document, covering both legacy FORMTEXT/FORMCHECKBOX/FORMDROPDOWN fields and modern content controls, across body and tables. It lacks an explicit verb like 'lists' and does not name sibling alternatives, but the intended behavior is clear.

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 a clear usage context: use this tool when you need all fillable form fields, including legacy and modern controls, in both the body and tables. It does not explicitly discuss when not to use it or name alternatives such as list_content_controls or list_fields.

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