jiji_inspect_workflow

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

Annotations already declare readOnlyHint=true, idempotentHint=true and destructiveHint=false, so the safety profile is covered structurally. The description adds genuine value beyond that: it discloses that secret controls (password/OTP/token) are filtered out of the returned surface, which an agent would not infer from annotations or schema. It doesn't describe what the visible page representation looks like, but the output schema presumably carries that.

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?

Three short sentences, zero redundancy, and the positive capability is front-loaded before the negative scope. Every clause carries distinct information.

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 a rich annotation set and an output schema, the description doesn't need to explain return values or safety. The one meaningful gap is the ordering relationship to jiji_open_workflow and jiji_capabilities — for a tool that reads an already-'mapped' workflow, whether the agent must open it first is the key missing fact.

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 a single required parameter with a 42-value enum and 0% schema description coverage, so the description is the only place semantics could be added — and it adds none, never explaining what a 'mapped workflow' is or how the enum values correspond to pages. The enum values are largely self-descriptive, which prevents this from sinking lower, but the description misses an easy opportunity to say 'one of the 42 mapped Jiji surfaces.'

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?

States a specific verb ('Read') and resource ('visible page and non-secret form controls') scoped to a mapped Jiji workflow, which is clearly distinct from mutating siblings like jiji_prepare_action and jiji_prepare_advert. It doesn't explicitly contrast with jiji_open_workflow, which is the closest sibling and whose relationship to 'mapped workflow' is left implicit.

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 clearly enumerates what the tool will not do (submit forms, upload files, change credentials, authorize payments), which functions as useful exclusion guidance. However, it never names an alternative — an agent isn't told to use jiji_open_workflow first, or jiji_prepare_action when it actually wants to act. Usage is implied by the exclusions rather than stated.

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