invoices_share_links_list

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

There are no annotations, so the description carries full burden for behavioral disclosure. It mentions status values (active/revoked/expired) which is useful, but it does not indicate whether this is a pure read operation, return ordering, filtering, pagination, or whether revoked/expired links are listed by default or require flags. For a list tool with no annotation safety profile, this is a meaningful gap.

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?

A single sentence frontloads the verb, resource, and returned fields with zero redundancy. Every element earns its place; status values are compactly enumerated. Excellent structure.

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?

The tool is a straightforward list operation with 2 well-documented schema parameters, so the description covers the core purpose. However, there is no output schema and no annotations, so the description should do more to clarify return-shape details (e.g., whether only non-expired links are shown, how view counts are aggregated, whether the list is paginated). For a moderately simple list tool this is adequate but not enriched.

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% at the parameter level—both uuid and companyId have descriptions. However, the description adds no value on top: it doesn't explain the relationship between uuid and companyId, that companyId is an override, or detail how these parameters shape the returned links. The description adds no semantics beyond what the schema already declares, 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 uses a specific verb ('List') with a clear resource ('all share links for an invoice') and enumerates what data is returned (view counts, expiry info, status). It clearly distinguishes from siblings like invoices_share_links_create and invoices_share_links_revoke, which are operational actions rather than listing. A clear 4, though it doesn't explicitly name its sibling alternatives as competing read tools.

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 a read-only listing use case but provides no explicit when-to-use guidance or exclusions. Context signals like 'required: uuid' suggest you need an existing invoice's UUID, which is implied but not stated. No alternative tool is named as an alternative, and it's not clear how this differs from other list operations in the suite for a non-obvious case.

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