get-sap-data

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

With no annotations present, the description carries the full burden. It discloses the operation is read-only and GET-only, warns that output is raw SAP JSON including __metadata, and advises keeping $top small. This covers the main safety and payload traits an agent needs; it does not mention error behavior or pagination, but those are less critical here.

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?

Four dense, purposeful sentences with no filler. The core purpose and safety trait are front-loaded, and every sentence adds either a routing rule, a usage case, or an important behavior warning.

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 generic OData fetch tool with a single parameter and no output schema, this description is nearly complete: it names when to use alternatives, enumerates intended use cases, describes the return shape, and warns about response size. The only notable omissions are error handling or pagination details, which are minor for this tool's purpose.

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?

The schema already documents the endpoint parameter at 100% coverage, so the baseline is 3. The description adds value by giving concrete endpoint examples and usage patterns such as A_BusinessPartner('1'), navigation properties, $expand, $count, and $metadata, which clarify what belongs in the parameter.

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?

Description opens with a specific action on a concrete resource: 'Fetch data from any SAP S/4HANA OData path (read-only, GET only).' It also explicitly distances itself from sibling tools by name, so an agent can tell exactly what this generic endpoint tool is for.

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 gives explicit routing guidance: prefer get-business-partners, get-sales-orders, or get-purchase-orders when applicable because they return less data, and use get-sap-data for other entities, key reads, navigation, $expand, $count, and $metadata. This is a clear when-to-use vs. alternatives statement.

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