peaka_get_project_metadata

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

Annotations already declare readOnlyHint=true, destructiveHint=false, openWorldHint=false, so safety is covered. The description adds real value beyond them by disclosing return shapes per format ('compact' returns tables with columns/relations; 'ddl' returns CREATE TABLE statements; omitting format returns full stored metadata) and the interaction constraint that includeSamples only works with a format.

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?

Three short paragraphs, front-loaded with the core action and followed by format details and the prerequisite. Mostly economical, though the middle paragraph opens with a broken fragment ('format makes the result much smaller:') that reads as a formatting glitch rather than prose.

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 output schema, the description carries the burden well by describing exactly what compact/ddl/default return, and the projectId prerequisite is covered. It omits guidance on result size for large projects (pagination or the compact format's role in avoiding huge responses is only half-stated) and says nothing about metadata staleness or when to call peaka_refresh_project_metadata.

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 coverage is 100%, so baseline would be 3, but the description adds meaning beyond the schema: concrete output structure for each format value, the rule that samples apply 'with a format,' and the fact that catalogId/schemaName filtering is optional. Minor gap: it does not explain whether catalogId and schemaName can be combined or what happens if both are supplied.

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?

States a specific verb and resource plus scope: 'Get metadata for all catalogs, schemas, and tables in the Peaka project in a single call.' The 'single call' phrasing implicitly distinguishes it from the granular siblings (peaka_list_catalogs, peaka_list_schemas, peaka_list_tables) without naming them, so an agent can mostly infer the distinction but must reason about it.

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?

Gives a clear usage context ('Use this tool to discover the data structure before writing queries') and an explicit prerequisite chain: call peaka_list_projects and ask the user for the projectId if unknown, then reuse it. It stops short of naming an alternative tool or an explicit when-not-to-use condition, so it is strong but not exhaustive.

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