DigiData

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

Annotations already declare readOnlyHint=true, destructiveHint=false and closed-world, so the safety profile is covered. The description adds genuinely new behavioral facts: the aggregation is bounded and database-side, SQL and tenant IDs are rejected, and the response echoes the applied measure definitions.

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 dense sentences, the operation list front-loaded and the two hard constraints (no SQL, no tenant ID) placed last where they are easy to scan. The operation enumeration is long but each term maps to real capability, so little is wasted.

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?

An output schema exists, so return values need no prose explanation. But for a 7-parameter tool with 0% schema coverage and required source/table/measures, the description leaves the required-parameter contract and the structure of filters/dateBuckets/measures largely undocumented, which is a real gap for correct invocation.

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?

With 0% schema description coverage on 7 parameters, the description carries the load: it names the measure operations that populate `operation`, and references grouping, date buckets, and structured filters, which maps to groupBy, dateBuckets and filters. However it says nothing about `source`, `table`, `limit`, the direction/percentile options, or the shape of a filter object, so the compensation is partial.

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 (aggregate/run measures) plus the full taxonomy of supported operations (count, distinct count, sum, percentile, rank, running-sum) and the two axes of scoping (grouping/date buckets, filters). The explicit 'Never accepts SQL' also separates it from the query_table sibling without the agent needing to open 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?

The constraints ('bounded', 'never accepts SQL or a tenant ID') implicitly steer the agent here for aggregated metrics rather than raw row retrieval, but no sibling is named and there is no explicit when-to-use/when-not statement relative to query_table or describe_table. Usage is inferable rather than stated.

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=true, destructiveHint=false, and closed-world scope. The description adds meaningful behavioral context beyond that: results are filtered to permitted tables/columns/relations, and it explicitly guarantees no sample rows are returned. It does not, however, discuss pagination or error behavior on a non-permitted table.

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?

A single dense sentence covering scope, returned fields, and a negative guarantee, with no wasted wording. The most important constraint ('schema only, never sample rows') is placed last for emphasis and is easy to scan.

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?

An output schema exists, so return values need not be re-explained, and the description still usefully previews them. Given only two schema-documented params and read-only annotations, the definition is essentially complete; the only omission is guidance on behavior when the table is not permitted.

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 both parameters and their provenance (list_tables, list_sources) are already documented in the schema. The description adds the 'permitted table' constraint but no new syntax or format guidance, so the baseline of 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 (describe) plus resource (table) and enumerates exactly what is returned: metadata, permitted columns, PostgreSQL types, nullability, keys, and permitted relations. It also implicitly separates itself from query_table by specifying 'schema only and never sample rows'.

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?

Usage is implied rather than stated: an agent can infer this is the introspection tool versus query_table for data, and 'one permitted table' hints at permission scoping. But no sibling is named and no explicit when-to-use or precondition (e.g., table must exist in list_tables output) is spelled out.

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=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered structurally. The description adds the notion of a 'permitted source' and 'safe' freshness, hinting at permission scoping, but does not elaborate on what it checks or any auth/rate constraints.

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 compact sentences with the core purpose front-loaded and the trigger immediately after. No filler, though the phrase 'safe synchronization freshness' is slightly vague.

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?

An output schema exists, so return values need not be described, and the description supplies purpose plus a usage trigger for a one-parameter tool. The remaining gap is the undefined 'source' argument, which is minor given the sibling list_sources.

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 0%, so the single 'source' parameter has no documented meaning in the schema, and the description does not explain its format or how it relates to list_sources. The name is fairly self-evident in context, which keeps this at an adequate rather than failing level.

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 ('Return') and resource ('synchronization freshness and status'), so the agent knows this is a status/diagnostic read rather than a data query. It is clearly distinct from siblings like query_table or describe_table, though it never explicitly contrasts itself with them.

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?

A concrete trigger is given: 'Use when data appears stale or unavailable,' which tells the agent when to reach for this over a plain query. No exclusions or named alternatives are provided, so it stops short of a 5.

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=true, destructiveHint=false and a closed-world scope, so the safety profile is covered. The description adds meaningful scoping context ('synchronized', 'permitted for this connection') and notes freshness/status fields, but says nothing about rate limits, ordering, or pagination; with an output schema present, return detail is not required.

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 short sentences, zero filler, and the scoping constraint plus the sequencing instruction are both front-loaded. Nothing repeats the tool name or the schema.

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 zero-parameter, read-only list tool with an output schema already describing the returned fields, the description covers what an agent needs to select and call it. The only omission is explicit routing against siblings like list_tables.

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 there is nothing to disambiguate and the baseline for a no-param tool applies. The description doesn't need to compensate for any parameter gap.

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 ... data sources') with a clear scope qualifier ('synchronized', 'permitted for this connection'). It implicitly distinguishes itself from list_tables by naming sources rather than tables, but never explicitly differentiates from its siblings.

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 an explicit sequencing rule: use this before choosing a table. That is real decision guidance, though it stops short of naming an alternative tool or stating when this should not be used.

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, destructiveHint=false and openWorldHint=false, so safety is covered. The description adds a genuinely useful behavioral fact the annotations do not: results are authorization-scoped ('permitted tables', 'permitted foreign-key relations'), meaning callers may see a filtered view of the catalog.

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, zero waste. The return-content inventory is front-loaded and the optional filtering constraint follows immediately, so an agent can stop reading as soon as it has what it needs.

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 zero-required-parameter, read-only listing tool with a full output schema, the description covers scope (permitted only), parameter provenance, and returned fields. Nothing needed to invoke it correctly is missing, and return-value detail is legitimately delegated to the output schema.

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% and the single parameter is self-documenting, so the baseline is 3. The description goes beyond the schema by stating that valid source values come from list_sources, which is provenance the schema itself does not supply.

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) and enumerates exactly what each entry contains — display names, descriptions, columns, keys, foreign-key relations — so an agent knows the shape of the result without opening the output schema. It does not explicitly distinguish itself from describe_table, which is the closest sibling, so it falls short of a 5.

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 gives clear guidance for the single optional parameter ('restrict to one source returned by list_sources'), which ties the tool to a sibling, but it never states when to reach for this tool versus describe_table or query_table. Usage is implied rather than framed as a decision.

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=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds genuine non-obvious behavior: results are bounded, pagination uses an opaque cursor, and the tool never accepts SQL or a tenant ID. That scope/security disclosure is real value beyond the annotations.

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 tight sentences, front-loaded with the core action and followed by the key constraint. No filler, every clause earns its place.

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?

An output schema exists, so return values need no explanation, and annotations cover safety. However, for a 7-parameter tool with 0% schema coverage, the description is thin on filter/operator semantics and cursor usage, leaving gaps an agent would need filled by guesswork.

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 0%, so the description must carry the load. It names the concepts for columns, filters, sort, limit, and cursor, which maps to most parameters, but provides no format or syntax detail (allowed operators, filter value shapes, cursor reuse). It partially compensates without fully covering the gap.

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 bounded rows from one permitted table.' The enumerated capabilities (columns, filters, sorting, limit, cursor) and the note that it returns rows rather than aggregates implicitly distinguish it from aggregate_table. It does not explicitly name any sibling, so it falls just short of a 5.

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?

There is no explicit when-to-use or when-not-to-use guidance and no named alternative (e.g., aggregate_table, describe_table). 'One permitted table' faintly implies a single-table scope constraint, but the agent is left to infer routing among siblings.

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