get_process_instance

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), yet the description goes further by disclosing access-control behavior: truncated field sets for Editors, secrets redacted in variables, and files returned as metadata only. These are non-obvious traits an agent could otherwise misreport to a user. Missing: behavior on an unknown/unauthorized instance_id.

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?

Two dense sentences: the first front-loads what the payload contains, the second qualifies it by role. The field inventory is long but each item maps to returned data, so it earns its place; only minor tightening would help.

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?

With no output schema, the description correctly takes on responsibility for describing return contents and access-dependent filtering, which it does thoroughly. The remaining gap is the single input parameter's origin and format, which matters for actually invoking the tool. Language mismatch with the English tool names is a minor usability note.

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?

There is one required parameter, instance_id, with 0% schema description coverage, so the description must carry the burden of explaining it. It never mentions the parameter, that it is a UUID, or where to obtain it (e.g., from list_process_instances). The schema constrains the type but adds no semantic meaning to compensate for the low coverage.

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 states a specific resource ('Uma instância de processo') and enumerates what is surfaced: status, steps with blocking state, open human tasks, generated files, owner and originating conversation. An agent can tell this is a single-instance detail read rather than a listing, but it never explicitly names similar siblings such as get_process_trail, get_process_command or list_process_instances to force the distinction.

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?

Usage is only implied: an agent must infer that this is the lookup of one instance, likely after list_process_instances returns an id. The role-based note (what an Editor sees versus admin/owner) is genuinely useful context, but it is access scoping, not when-to-use guidance, and no alternative tool is named or excluded.

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