Get datasource schema

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 discloses the tool performs introspection and returns schema (tables, columns, keys), and implies caching via the 'refresh' parameter wording. However, it doesn't disclose side effects (e.g., whether refresh mutates the cache, auth requirements, permission levels needed, or rate limits). For a read-style introspection tool, basic transparency is there but behavioral detail is thin.

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 efficient sentence that conveys purpose and scope without waste. It's front-loaded with the key verb and resource. Slightly more context (return format, when to use refresh) could be added without bloat, but the current text is appropriately concise.

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?

With no annotations and no output schema, the description must cover behavior adequately. It states what the tool returns (schema: tables, columns, keys) but not the structure of that return, pagination behavior, or size expectations for large data sources. The caching nuance via 'refresh' is mentioned but not elaborated. For a moderate-complexity introspection tool, it's adequate but leaves gaps.

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 both parameters (datasourceId and refresh) are documented in the schema. The description adds the introspection framing (tables, columns, keys) that helps interpret the output but adds little to the 'refresh' boolean semantics beyond what the schema states. Baseline 3 is appropriate given full coverage and minimal extra description value.

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 states the verb (returns/introspects) and resource (datasource schema) with specific scope (tables, columns, keys). It distinguishes from siblings like appsmith_list_datasources (which lists datasources, not their schemas). However, it could more explicitly differentiate from related introspection tools like get_page or list_queries. Overall it's clear but doesn't strongly emphasize sibling differentiation.

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 the tool is for retrieving datasource schema, but provides no explicit when-to-use guidance or exclusions. The 'refresh' parameter hints at cache behavior, but the description doesn't state when the cached vs fresh path is appropriate. Sibling names suggest it fits into a schema-exploration workflow, but no alternatives are explicitly named.

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