erpnext_process_trace

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds the behavioral scope of tracing across multiple modules, but does not explain how the trace is constructed or what constraints apply (e.g., how filters combine). This adds some value beyond the annotations but not rich behavioral detail.

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 a single front-loaded sentence: the verb and object come first, followed by a compact list of covered domains. There is no filler or repetition of schema/annotation information, so it earns a high conciseness score.

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?

For a tool with nine optional parameters, zero schema descriptions, and a broad trace operation, the one-line description leaves key invocation questions open, such as how to identify the starting flow and what happens when no filter is supplied. The output schema and read-only annotations cover the return shape and side-effect profile, but they do not compensate for missing parameter semantics. The description is a good selector-level overview but not enough for confident correct 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?

With 0% schema description coverage, the description needed to define the nine parameters but only indirectly references sales, buying, production planning, subcontracting, and work orders. Parameters like tag, limit, company, and item_code are not explained or mapped to invocation behavior. The domain list gives a partial hint at best.

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 leads with a specific action ('Trace') and a concrete resource ('one ERPNext business flow'), then enumerates the modules it spans. This makes it easy to distinguish from sibling tools like doc_get or report_run, which operate on single documents or reports rather than cross-module flows.

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 makes the intended use case clear: end-to-end business-flow tracing across ERPNext domains. It does not explicitly name alternatives or state when not to use this tool, but the scope is specific enough that an agent can select it for flow-tracing tasks. Missing explicit exclusions keeps this from a 5.

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