Postings: get postings

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

Annotations already cover readOnlyHint=true, destructiveHint=false, and idempotentHint=true, so the description doesn't need to repeat safety traits. It adds the critical limit of 1000 postings per request, which is a behavioral constraint beyond annotations. It also mentions the response includes row count and an array, providing some transparency, though output schema likely covers details. This is good value beyond structured fields.

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 well-structured, starting with a clear READ-ONLY flag, then a purpose statement, key limits, and usage advice. It is concise without excess, though it redundantly repeats 'get postings' in the description. Overall, it is efficiently organized and front-loaded with the most important 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?

Given 11 parameters with full schema coverage, an output schema, and safety annotations, the description is largely complete. It covers the core purpose, the 1000-row limit, and practical usage tips. It doesn't explain every parameter or edge case, but the schema and output schema fill those gaps. The description adequately complements the structured data for an agent to use the tool correctly.

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 description coverage is 100%, so all parameters are already documented in detail, including formats and defaults. The description's mention of 'Supports `limit` and `offset`' is redundant with the schema, and the advice about bounded date ranges is more usage guidance than parameter semantics. It adds minimal new meaning beyond the schema, so baseline 3 is appropriate.

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 states the tool's action and resource: 'Get postings for a specified customer account' and 'read the booking journal'. It specifies a verb (get), a resource (postings), and a scope (customer account), making it distinct from sibling tools like postings_cancel or postings_create_*. The READ-ONLY label further disambiguates it from write operations.

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 explicitly says 'Use to read the booking journal, filtered by date range or posting account', providing clear context for when to invoke it. It also gives practical advice to 'Ask for a bounded date range rather than paging through a whole financial year', which is helpful guidance. However, it does not explicitly name alternatives or exclusions, though the sibling list makes the read/write distinction obvious.

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