freshbooks_list_records

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

Annotations only declare readOnlyHint=true, so the description carries additional useful context: it discloses the return shape ('items plus page/pages/total') and notes that some resources are gated by plan or role and 'will report that rather than returning rows.' This is meaningful behavioral information beyond the structured annotation.

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 only two sentences and gets the core purpose, scope, return shape, and access-gating caveat out quickly. The first sentence is long with a parenthetical enumeration, but every phrase carries useful information and there is no repetition of schema content.

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 reasonably summarizes the return as 'items plus page/pages/total' and calls out plan/role gating. However, it does not cover how pagination parameters interact with the response, how search filters should be represented, or how to know when a resource is not available through this endpoint. Useful, but not fully complete for a generic reader with four parameters.

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 exactly 50%, with resource and search documented in the schema but page and per_page left without descriptions. The tool description adds resource examples but does not explain pagination parameters, search-object usage, or the fact that resource must match an enum. It provides only marginal value beyond what the schema already states.

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 clear verb+resource: 'List any FreshBooks accounting resource by name.' It positions itself as the generic reader and enumerates long-tail resources, which helps distinguish it from dedicated list tools. However, it also lists 'expense categories' which already has a dedicated sibling tool (freshbooks_list_expense_categories), slightly blurring the boundary.

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 phrase 'alongside the ones with dedicated tools' implies the generic tool is for resources without dedicated list tools, but it never explicitly states when to prefer this tool over a sibling. The inclusion of 'expense categories' despite a dedicated sibling makes the intended usage less crisp. Minimal guidance for resource access is present but no explicit exclusions are given.

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