costing_pl_list

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

Beyond the readOnlyHint annotation, the description discloses significant non-obvious behaviors: margin-descending sort, closed-project exclusion unless status='closed', exact B00 filtering, degradation to fxBaseMissing for foreign-currency rows, saved view filter merging, and the basisDegraded honesty flag shared with costing_project_pl. These details substantially exceed the annotation baseline and materially aid an agent in interpreting results.

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 dense and information-rich, covering many edge cases, but it mixes German and English and uses cryptic codes (B00, G00) without explanation. The structure is logical—output shape, filtering, degradation, saved views, shared computation—but the phrasing is not lean and some sentences are overloaded. It earns its place but sacrifices readability.

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 tool's complexity (6 parameters, no output schema, no parameter descriptions), the description covers the output shape and several behavioral edge cases, but leaves core parameters undefined and does not describe the exact return fields. An agent can call it correctly for the covered filters but may misuse asOf, basis, or includeOpenTime. Incomplete but not severely so.

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 0%, so the description carries the burden for all 6 parameters. It explains only status (via closed/B00 semantics) and savedViewId (merge behavior). The parameters asOf, basis, includeOpenTime, and workspaceId are never mentioned, leaving an agent guessing about their meaning and accepted values. This is a major gap for a tool with no schema descriptions.

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 states a specific verb and resource: it reads a portfolio of project P&L summaries, one row per project, sorted by margin descending. It directly answers the business question 'welche Projekte oder Mandate tragen?', and references sibling costing_project_pl to place itself as the portfolio-level version of the same computation, distinguishing it without ambiguity.

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?

It gives clear context: this is the read for portfolio-level project profitability, with explicit filter semantics for closed projects, B00 status, and saved view merging. It does not explicitly name alternatives or say when not to use it, but the referenced costing_project_pl and the portfolio framing imply the boundary. No contrary usage guidance is present.

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