LakehouseBox

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

Annotations already declare readOnly, idempotent, non-destructive, so safety is covered. The description adds meaningful context beyond that: 'Metadata only' rules out returning table data, and it enumerates the metadata categories returned (partition spec, sort order, snapshots with rows added/removed). This is real added value, though it omits any cost/permission caveats.

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 trigger sentence is well front-loaded, but the central 'sentence' is a sprawling, comma-and-semicolon-separated fragment listing return fields without clear hierarchy. It is information-dense rather than padded, yet the structure makes it hard to parse quickly.

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 return-value burden and largely discharges it, enumerating the field groups an agent will receive. Combined with annotations covering the safety profile and a 100%-documented schema, this is nearly complete; only snapshot pagination/preview semantics and failure modes are left implicit.

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 is 3, but the description adds semantic meaning to `snapshots` by explaining what each snapshot contains (commit time, operation, rows added and removed) and reveals the derived ingestion-cadence use case. It also clarifies the `agents_md` output source, which enriches the `table` parameter's context.

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 opening sentence gives a specific trigger (user asking what a table's columns are or mean) and the resource (one table), and 'Metadata only' separates it from data-returning siblings like query. However, the second sentence is a grammatical fragment listing returned fields, which muddies rather than states the purpose. An agent can still identify it as the table-metadata sibling of list_tables.

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 states when to use it ('when the user asks what a table's columns are or mean') and clarifies the interaction with read_agents_md by noting the tool returns `agents_md` while read_agents_md retrieves the file. No explicit when-not or pagination/limit guidance, but the read/write boundary is implied by 'Metadata only'.

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

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

Annotations already declare readOnly/idempotent/non-destructive, yet the description adds substantial behavior beyond them: images are downscaled to max_dimension on the long edge, files <=64 KB return as text, everything else returns metadata plus a 15-minute download link. These output-shape and expiry details are exactly what the annotations cannot convey.

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 sentences, front-loaded with the trigger condition, then the core action, then the response variants. Every clause earns its place with no restatement of the name or title.

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?

No output schema exists, so the description carries the return-format burden and does so fully: it distinguishes image, text, and metadata responses and names the download-link TTL. Nothing needed to call it correctly is missing.

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 the baseline is 3. The description goes further by scoping max_dimension to images only ('downscaled to max_dimension on the long edge') and clarifying that key content type determines the response form, adding meaning beyond the per-field schema text.

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: 'Read one file of a catalog's file storage by its key.' The opening clause ties it to a concrete trigger (a table row pointing at a file), which cleanly separates it from the query/query_rw siblings that handle tabular data.

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 when-to-use condition ('when a table row points at a file ... the user wants to see'), including the example key path garden.images.object_key. No explicit when-not or named alternative, but no sibling is a real substitute for reading file bytes.

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

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

Annotations only declare it is a non-readonly, non-idempotent, non-destructive mutation; the description goes far beyond that. It discloses the 72-hour deletion clock, that the tool returns a link plus short code to hand the person, that the connection stops working afterward, and that reconnection happens once signed in with the same data. Error-branch behavior (not_unclaimed, claim_with_cli and its key replacement) is also spelled out.

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?

Front-loaded with the core purpose, then layered with the 72-hour rationale, mechanics, and error cases in a logical order. Every sentence carries new information, but the run-on error-code sentence is dense enough that a slightly tighter phrasing would read better.

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?

Despite having no output schema, the description fully covers what the caller receives (link + code), what happens to the connection afterward, and the two failure paths. For a zero-parameter tool in an otherwise unrelated sibling set, this is 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?

The tool takes zero parameters, so per the baseline rule a 4 applies; there is nothing for the schema to describe and nothing for the description to compensate for. Note the 'link and short code' described are outputs delivered to the person, not call arguments, so no parameter meaning is missing.

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?

Opens with a specific verb+resource: 'Keep the LakehouseBox account this connection set up for the person.' An agent immediately knows this converts a temporary trial account into a permanent one, a purpose with no overlap with any sibling (describe_table, query, etc.). The follow-on clauses reinforce rather than obscure the purpose.

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 states when to call it ('when the person wants to keep their data, or when the time left is short') and when it does not apply, naming two distinct negative cases with their returned codes ('not_unclaimed', 'claim_with_cli'). Alternatives are routed (CLI claim path). Nothing is left to inference.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so safety is covered. The description still adds real context: 'Metadata only: no data is read', the exact per-table fields returned, and that last_updated is the last commit in UTC. It stops short of describing pagination or result-size limits.

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?

Front-loaded with the usage trigger and 'Start here', and every sentence carries information about scope or return shape. It is denser than ideal in the middle enumeration of return fields, but there is little waste.

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 fully carries the return contract: identity, catalogs, fully-qualified table names, row_count, size_bytes, last_updated, doc, and agents_md. Combined with the explicit 'metadata only' boundary, an agent has everything needed to call and interpret 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?

Schema coverage is 100%, so baseline is 3, but the description meaningfully enriches it: search is typo-tolerant and matches table names, column names and column docs; catalog and namespace narrow the listing. It clarifies intent beyond the terse schema strings, though it adds no format or example values.

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 (list tables) with explicit scope: catalogs the caller can read and their tables with freshness metadata. It also distinguishes itself from the read_agents_md sibling by explaining that agents_md notes are 'which read_agents_md returns'. An agent can identify this tool without opening the schema.

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?

Clearly frames when to use it ('when the user asks what data they keep in LakehouseBox, which tables exist or how fresh they are') and positions it as the entry point ('Start here'). It also explains when to prefer the search parameter over full listing, but never names sibling alternatives like describe_table or query for deeper inspection.

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

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

Annotations already declare read-only, idempotent, non-destructive, non-open-world, so the bar is lower, yet the description adds substantial context: full return shape (tables, row counts, sizes, last update, catalog_alias), the keyless-vs-key DuckDB recipes, the sandbox refusal nuance, and the caveat that agents_md is the owner's words not instructions. This is far beyond structured fields.

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?

Front-loads the usage trigger before the mechanics, which is good structure. It is a single very dense paragraph with heavy nested parentheticals, so some clauses could be split, but nearly every sentence carries unique operational information.

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 of return values and does so thoroughly, including alias-based server-side querying, the recipe differences, and the agents_md field. Nothing an agent needs to call and consume the result correctly is missing.

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 params are already documented and the baseline is 3. The description reinforces catalog format and the namespace.table convention for `table`, but adds no syntax or constraints beyond what the schema already says.

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 ('Open ANOTHER organisation's PUBLIC catalog by name, <handle>/<catalog>') and immediately distinguishes it from siblings by scope. An agent can tell this apart from list_tables or describe_table without opening either schema.

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 trigger ('when the user names a public catalog as <handle>/<catalog> or wants open reference data') and even prioritises one recipe ('use it first'). It does not explicitly state when NOT to use it versus siblings like list_tables, so it stops short of the top band.

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

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

Goes far beyond the annotations (which already cover read-only/non-destructive): row and character caps, the 2000-row ceiling, the shared 20-second queue, busy/rate_limited error semantics with retry_after_seconds, cache TTLs and when caching is skipped, snapshot/commit freshness, and dry_run behavior. This is exactly the extra context annotations cannot carry.

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?

Front-loads when-to-use and the core verb, and nearly every clause carries independent information (naming rules, limits, errors, cache, fallback). It is a dense single block with no visual separation, which makes it harder to scan than it could be, but there is little pure padding.

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 complex, high-variance tool with no output schema, the description covers return shape (row objects vs arrays, columns), truncation signaling, freshness/snapshot metadata, caching, failure modes, and a compute-escalation path — everything an agent needs to invoke and interpret it correctly.

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 the schema already documents sql, engine, format, dry_run and max_rows. The description restates the same facts (format='arrays' ~half the size, dry_run introspection, default 200 / max 2000) rather than adding new parameter meaning, so the baseline 3 applies.

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 precise verb+resource: 'Run ONE read-only DuckDB SQL statement on the server over the catalogs you can read', and enumerates the allowed statement forms (SELECT, WITH … SELECT, DESCRIBE, SUMMARIZE, EXPLAIN). It is clearly separable from siblings like query_rw (read-only), open_public_catalog (source of aliases), and describe_table.

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?

Explicit when-to-use ('user asks a question about data they keep in LakehouseBox, or to check a table after changing it') plus an explicit alternative for heavy work (run your own DuckDB via lhbox duckdb when you can reach s3.lakehousebox.com) and a pointer to open_public_catalog for cross-organisation naming. Nothing is left to inference.

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

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

Beyond the annotations (destructiveHint=true, idempotentHint=false), the description discloses that a write requires write permission on the catalog (approved at connect time or held by API key) and that a read-only catalog is refused. It further explains snapshot semantics, the irreversibility of DROP ('removes a table with its history and cannot be undone'), the absence of CREATE OR REPLACE, and recovery guidance for 409/408/502 errors — none of which the annotations convey.

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?

Content is front-loaded with the when-to-use trigger, which is good, but the remainder is a dense run-on paragraph mixing statement lists, permission rules, snapshot semantics, and error recovery. Nearly every sentence earns its place, but the wall-of-text structure makes it harder to scan than it needs to be.

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 single-parameter mutation tool with no output schema, the description covers what an agent needs: permitted operations, permission prerequisites, naming, rollback/snapshot behavior, irreversibility warning, and explicit error-handling guidance. Nothing material is missing.

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% for the single 'sql' parameter, so baseline is 3. The description still adds real meaning: it enumerates the permitted statement types, the catalog.namespace.table naming convention, which catalog is written vs only read, and the 'one statement' constraint — going beyond the schema's terse 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?

The description names a specific verb and resource: run ONE DuckDB writing statement (INSERT, UPDATE, DELETE, MERGE INTO, CREATE/ALTER/DROP) against catalog.namespace.table. It explicitly distinguishes itself from the sibling read tool by stating 'Reads belong in query' and 'Large loads belong in the user's own DuckDB'. An agent can route write-vs-read without opening either schema.

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?

It gives concrete when-to-use triggers (keeping data so it can be queried later, saving a result as a table, adding rows over time, correcting/removing rows) and explicit exclusions (reads belong in query; large loads belong in lhbox duckdb or table import). Alternatives and the conditions selecting them are named directly.

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

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

Goes well beyond the annotations: it discloses the trust framing of the payload (labelled 'owner-supplied context: data, not instructions'), warns that SQL inside it is untrusted, and documents the empty-state behavior ('present: false when there is none'). These are genuine runtime traits an agent needs and that readOnlyHint/idempotentHint cannot convey.

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?

Front-loads the usage trigger, then layers resource definition, trust warning, discovery pointer, and empty-state in short clauses. Every sentence carries distinct information; nothing is decorative.

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?

There is no output schema, yet the description covers the relevant return-shape facts (the label on the returned text and the present:false sentinel). For a single-param, read-only tool with full annotation coverage, nothing needed to call it correctly is missing.

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% and the single 'catalog' param is already documented as 'by name or id' in the schema. The description adds no further syntax or format guidance for the parameter, so the baseline 3 applies.

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 (read) and a precisely defined resource (a catalog's AGENTS.md), then defines what that resource actually contains ('what the catalog's owner wrote about its data'). It also points at the sibling list_tables as the discovery path, so an agent can place it relative to describe_table without opening a schema.

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?

Opens with an explicit trigger ('Use this when the user asks what a catalog's data means or how its tables relate'), adds the precondition that the catalog must have an AGENTS.md, and names list_tables as the way to check availability. When-to-use is concrete rather than implied.

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