execute_odata_query

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

Discloses that GET returns CSV and POST/PATCH/DELETE return JSON, which is valuable beyond schema. However, with no annotations, description carries full burden; it omits side effects, permissions, error handling, or idempotency. Adds some context but incomplete for a CRUD tool.

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?

Two sentences, front-loaded with core purpose, no wasted words. Efficiently conveys return format and usage recommendations.

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 tool complexity (10 params, CRUD, no output schema), description is adequate but has gaps: does not mention pagination behavior (top/skip are in schema but not described), single-record vs list retrieval via entityKey, or error handling. Points to siblings for discovery but could be more 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 description coverage is 100%, so baseline is 3. Description does not add significant meaning beyond schema; it only hints at using sibling tools for valid input values. No parameter-specific enrichment in description.

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?

Clearly states it executes OData CRUD operations against SAP S/4HANA, with specific verb and resource. Distinguishes from sibling tools discover_sap_services, get_entity_metadata, and get_field_values, which are used for preparation.

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?

Explicitly recommends using sibling tools before write operations for discovery of service names, field names, and valid input values. Provides clear context but does not cover all usage scenarios (e.g., when to use GET vs POST is inferred from method parameter).

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