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

With no annotations present, the description carries the burden and does disclose a meaningful non-obvious trait: role-based row filtering (owner/office see all, field workers see only their own entries). That prevents an agent from misreading a short result as an error. It stops short of disclosing pagination, ordering, result-size limits, or date-field semantics.

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?

Two short sentences with no waste; the scope modes come first and the visibility rule second. Nothing is repeated from structured fields and every clause earns its place.

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 five-parameter, annotation-free, output-schema-free list tool, the description covers scoping and permissions but leaves the agent guessing about return shape (how the category totals are presented), pagination, ordering, and the exact date semantics. Adequate but with real gaps an agent would hit on first call.

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 0%, so the description must compensate for five undocumented parameters. It meaningfully explains job_id, shop_id, from/to, and hints at category, but leaves key ambiguities: whether from/to are inclusive, which date field they filter on, whether job_id and shop_id compose or conflict, and that all parameters are optional.

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?

Specific verb implied (list) plus resource (expenses) and two distinct scoping modes (on a job, or across the shop between dates) with category totals. It is distinguishable from the mutating siblings expenses_add/expenses_update/expenses_remove. It does not, however, differentiate itself from costs_job/costs_jobs, which read as adjacent analytical siblings.

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 implies the two usage modes (job-scoped vs shop+date-range) and states who sees what, which helps an agent pick a call shape. But it never says what happens if both job_id and shop_id are supplied, what the default scope is given zero required parameters, or when to prefer costs_job or reports_* instead.

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