konsulto_list_assets

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

No annotations are provided, so the description carries the burden. It indicates a read operation ('list') and specifies return fields, but it does not disclose behavior like pagination (despite the limit parameter), potential large result sets when listing tenant-wide, or any permission requirements. The description is adequate but lacks depth on side effects or resource consumption.

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 exceptionally concise: two sentences that immediately convey purpose, scope, return content, and a related tool. No extraneous information. Every word is justified.

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 explains return fields (name, type, identifiers) and mentions matching evidence. The three parameters (audit, q, limit) are covered enough for basic usage. However, it could be more complete by noting that results are paginated via the limit parameter, and that tenant-wide listing may return many assets. Overall, it is fairly complete for a list operation.

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 67% (audit and q have descriptions). The description adds value by explaining the audit parameter's scope effect ('in the audit or tenant-wide') and stating return fields. However, it does not describe the limit parameter (not in schema description either) and 'q' is already explained in schema. The description partially compensates for the missing schema documentation but leaves a gap for limit.

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 action ('list assets'), the resource ('assets'), and the scope ('in the audit or tenant-wide if no audit filter'). It also mentions the returned fields (name, type, identifiers) to help match evidence. This distinguishes it from sibling tools like konsulto_create_asset (create) and konsulto_link_asset (link).

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 provides a clear use case: 'match evidence to the right asset' and directs to use konsulto_link_asset for attaching. It implies when to use this tool (listing assets) but does not explicitly state when not to use it or list alternative tools. However, the guidance is helpful and context-appropriate.

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