get_asset_details

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

No annotations are provided, so the description carries the full burden. It is transparent about the tool's read-only nature (implicit via the GET endpoint note) and thoroughly discloses the output structure. It does not explicitly state 'does not modify data' or discuss potential errors, permissions, or rate limits, but for a metadata retrieval tool, the behavioral expectations are clearly conveyed.

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 long but well-structured with clear headings (Use this tool when, What you'll get, Required parameters, etc.). Every section contributes useful information, though there is some redundancy between 'Use this tool when' and 'Use cases' sections. It is front-loaded with the primary action and remains organized throughout.

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 (returns comprehensive metadata, no output schema), the description compensates admirably. It lists the full spectrum of returned information, includes the API endpoint for context, provides example queries, and covers parameter usage. It leaves little ambiguity about what the tool does and when to invoke it.

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 describes all parameters with examples (100% coverage), so baseline is 3. The description adds value by providing real-world example values (e.g., 'SAP_SC_FI_AM_FINTRANSACTIONS'), explaining the purpose of expand_fields with examples, and mapping parameters to use cases. This goes beyond the schema's dry field names.

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 begins with a clear, specific verb+resource statement: 'Get comprehensive metadata for a specific SAP Datasphere asset.' It then enumerates the detailed metadata fields (dimensions, measures, consumption URLs, relationships, etc.), which clearly distinguishes this tool from siblings like get_asset_by_compound_key or list_space_assets by focusing on a single asset's complete metadata.

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 an explicit 'Use this tool when' section with concrete scenarios (e.g., 'Show me details about the Financial Transactions asset') and a 'Use cases' list. However, it does not explicitly mention when not to use it or suggest alternative tools, stopping short of the full 5-point criteria for exclusions/alternatives.

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