wafeq_journal_line_items_list

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

The description discloses behavioral traits well beyond the annotations: rows carry no transaction-date field, created_ts is write-time only and frequently falls in a different month, and the endpoint is cursor-paginated unlike the rest of the API. These are high-value facts an agent cannot infer from readOnlyHint, openWorldHint, or idempotentHint. The READ-ONLY marker is consistent with readOnlyHint=true, so no contradiction exists.

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 compact, front-loaded with the endpoint header and the critical NO DATE FIELD caveat before any optional detail. Minor redundancy: 'List journal line items' appears twice within the body and is repeated as the title, so one sentence could be dropped without losing 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?

For a 16-parameter, no-output-schema list endpoint, it covers the two riskiest invocation details — date semantics and pagination style — and routes to the correct sibling for dated data. It leaves unspecified how multiple filters combine and what the response shape is, but the schema already documents each filter and no output schema exists to elaborate, so the description is complete enough for safe selection and 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?

Schema coverage is 100%, setting the baseline at 3, and the description adds meaning above that baseline by clarifying that date_after/date_before operate on the real transaction date while created_ts/modified_ts are write-time stamps, and that cursor+page_size are the pagination pair. This prevents the agent from treating the schema's terse 'Date' entries as interchangeable with timestamp filters.

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 and resource — 'List journal line items' — backed by the explicit API path GET /journal-line-items/ and a READ-ONLY marker. It differentiates from siblings by naming wafeq_account_ledger as the alternative for rows that carry their date, so an agent can tell this list endpoint apart without opening other schemas.

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?

Gives explicit when-to guidance: 'To work by transaction date, filter with date_after/date_before, which DO operate on the real transaction date.' It also names an exclusion condition and alternative ('For rows that come back already carrying their date, use the wafeq_account_ledger tool instead') and warns against a misuse pattern (reporting created_ts as the transaction date).

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