List positions

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds valuable behavioral context: pricing in cents, the effect of referencing position_id in documents, the compact default field set, the response shape, and pagination semantics. This goes well beyond the annotations and gives the agent a clear model of what the tool returns and how it behaves.

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 and well-structured: it starts with the main action, then clarifies domain terms, notes currency convention, explains field selection, and lists the return structure. Every sentence adds value with no redundancy or filler.

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 there is no output schema, the description fully explains the response format including total, count, page, pages, has_more, next_page, and items[]. It also covers pagination continuation, field selection, and the cents convention. This is complete for a list tool with optional filters and pagination, leaving no major gaps for an agent to invoke it successfully.

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 the input schema already documents all parameters. The description adds some context (e.g., 'Prices are integers in cents' and 'pass fields for specific columns'), but these are largely restatements or extensions of the schema descriptions. Since the schema does the heavy lifting, a baseline of 3 is appropriate with only marginal added value.

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 'List positions from easybill with optional filters and pagination' and further defines positions as the 'reusable article catalogue (products, services and text blocks)', which distinguishes this list tool from other list tools like easybill_list_documents or easybill_list_customers. The verb and resource are specific and unambiguous.

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 conveys when to use the tool (to list positions), and provides practical usage guidance like using 'fields' for column selection and 'next_page' for pagination. It does not explicitly name alternative tools (e.g., easybill_get_position) for singular retrieval, but the purpose and context are clear enough for an agent to select it appropriately.

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