fluig_process_def_states

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

The description offers valuable behavioral insight beyond the schema or annotations. The warning 'esta tool já manda os expands certos' (this tool already sends the correct expands) tells the AI agent how the underlying API call is structured and why it works, preventing incorrect manual invocation.

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 information is front-loaded with the most critical distinctions and behavioral quirks (the two warning notes). The language is dense but entirely necessary for avoiding API misuse, making it extremely efficient.

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 that this is an API wrapper for a complex system (Fluig), the description is highly complete. It addresses the primary functional difference, the inherent limitations of the REST v2 endpoint, and the operational behavior (expands), leaving the AI agent with no major gaps in understanding the tool's capabilities and constraints.

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?

While the schema coverage is 100%, the description adds vital conceptual meaning by explaining *why* specific data (like process definition vs. runtime state) is being retrieved. It contextualizes the parameters for the purpose of a definition retrieval, adding value even when the schema is comprehensive.

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 defines the tool's purpose: obtaining the definition (activities, BPMN type, deadlines, assignment mechanisms) of a process. Crucially, it differentiates itself from the sibling tool, `fluig_process_states`, by specifying that it deals with the definition, not the runtime status of a single request.

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 provides explicit usage constraints by warning the user when the tool will return incomplete data (i.e., if necessary configuration fields aren't expanded). It then immediately prescribes the correct alternative tool (`fluig_process_export_xml`) for those specific missing fields, providing perfect usage guidance.

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