reports_sources

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

The readOnlyHint annotation already marks it read-only, but the description adds valuable behavioral context: it is 'a read model' (reinforcing non-mutation), and it discloses that custom fields (cf:) appear dynamically once defined (OP7), and that access is gated on A24 reports.read. This goes beyond the annotation and informs the agent about permission requirements and dynamic data updates.

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 a single dense sentence that packs multiple concepts (registry, fields, dynamic custom fields, permission gate) without clear breaks. It is not front-loaded with the most critical information; starting with 'Datenquellen (F01)' may confuse. While concise in length, the structure is unwieldy and could be split into clearer sentences.

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 the absence of an output schema, the description provides a solid list of returned fields (source id, title, entity kind, accounting-record flag, module availability, published columns) and explains the dynamic inclusion of custom fields. It covers the main behavioral aspects, but misses explaining the workspaceId parameter or any pagination/default behavior. For a simple read with one parameter, it is fairly complete.

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% and the description does not mention the workspaceId parameter at all. With only one parameter and no description, the agent is left to infer its meaning, though it is a common identifier across many tools. The description fails to compensate for the schema's lack of documentation, so this dimension scores low.

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 identifies the tool as a read model for the REPORT_SOURCES registry, listing the exact fields returned (source id, title, entity kind, accounting-record flag, module availability, published columns). It distinguishes itself from siblings like reports_runs (execution) and reports_list (listing reports) by specifying its read-only nature and content. The verb is implicit but the resource and scope are explicit.

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 usage for retrieving data source definitions needed for report building, and mentions a permission gate (A24 reports.read), but does not explicitly state when to use this tool versus alternatives like reports_preview or reports_runs. No explicit exclusions or alternative routing is provided, leaving the agent to infer the context.

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