Caspio

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

Annotations already flag destructiveHint, but the description adds crucial behavioral context: deletion is irreversible, a broad WHERE clause deletes all matching records, single-record deletion requires a unique field filter, and the call returns the deleted count. These go well beyond the structured 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?

The description is multi-sentence but every sentence contributes essential guidance: purpose, irreversibility, WHERE semantics, single-record strategy, return count, and field-name sourcing. It is front-loaded with the core action and remains tightly organized without redundancy.

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 destructive tool with no output schema, the description fully covers what an agent needs: required WHERE clause, broad-delete danger, irreversible nature, return value, prerequisite discover_tables call, and field-name validation. Nothing critical is left to inference.

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 adds extra meaning for the 'where' parameter: Microsoft SQL Server syntax support, case-insensitive field names, and a warning that field names must come from discover_tables. It also reinforces that tableId must be the discovered ID, not a name.

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 states a specific action ('Deletes one or more records'), a specific resource ('a Caspio table'), and a precise selection criterion ('match the WHERE clause'). It clearly differentiates from view-related siblings by scoping to tables and mentioning tableId from discover_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?

It gives clear context: use this tool to delete table records matching a WHERE clause, call discover_tables first, and avoid guessing field names. It does not explicitly name delete_view_records as an alternative, but the table-vs-view distinction is clear enough from context.

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 destructiveHint annotation, the description discloses that deletion is irreversible, returns a count, and behaves differently for multi-table views. It also notes case-insensitivity and the need to use field names from discover_views, adding important behavioral context.

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 dense but each sentence adds value: it covers irreversibility, multi-table behavior, WHERE requirements, single-record deletion, count return, and the discovery prerequisite. It is well-structured and front-loaded with the core action.

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 destructive operation with two required parameters, the description is complete: it explains prerequisites, return value, important constraints, and even includes examples. There is no missing information an agent would need to call 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?

The schema already documents both parameters with examples, but the description enriches them: it explains that WHERE is required and supports SQL syntax, that a broad WHERE deletes all matching records, and that viewId must come from discover_views. This goes beyond the schema's basic descriptions.

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 action (delete records through a Caspio view), the target (records matching WHERE), and distinguishes it from table deletion. It also explicitly mentions the WHERE clause requirement, making the purpose unambiguous.

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?

Provides explicit when-to-use: for deleting records from a view, with prerequisites (call discover_views first). It explains the irreversibility and gives guidance on how to delete a single record, and warns about broad WHERE clauses. It also indicates that in multi-table views only primary table records are deleted.

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 mark the tool as readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds meaningful behavioral context: it is a single-call discovery operation, returns field schemas, and clarifies that directories support SAML federation and may house different user types. This goes beyond the annotations without contradicting them.

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 front-loaded with the core purpose and returns information, followed by domain context and parameter guidance. The SAML and multi-directory explanations are helpful for understanding what directories are, though slightly more verbose than strictly necessary for invoking the tool. Still, every sentence contributes value.

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 appropriately states what the tool returns: id, name, and field definitions. It also explains why the id matters, how to filter or list all, and the optional parameters are fully covered by the schema. For a read-only discovery tool with four optional parameters, the description is sufficient 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?

Schema description coverage is 100%, so the schema already documents all four parameters fully. The description adds a practical note about nameFilter (search vs. list all) and mentions the id's downstream use, but overall it does not add substantial semantic detail beyond the schema. Baseline 3 is appropriate.

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 uses a specific verb ('Discovers') with a clear resource ('directories in the Caspio account'), and immediately distinguishes itself from sibling tools like discover_tables and discover_views by explaining that directories are identity/authentication services. It also states the primary output (id, name, field definitions) and even links to query_directory_users, making the tool's role unambiguous.

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 usage context: it is the tool to call for directory discovery, can return all directories or filter by name, and the returned id is needed for query_directory_users. It does not explicitly contrast with discover_tables/discover_views or state when not to use it, so it misses full exclusion guidance, but the context is strong.

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 mark the call read-only, open-world, and non-destructive, and the description adds substantial behavior: it discloses that auto-generated fields are not editable and should be excluded from insert/update payloads, explains Caspio data types, and warns to use field names rather than labels in queries. This is exactly the contextual behavior an agent needs and goes well beyond the annotation hints.

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 front-loaded, with the core purpose in the first sentence and supporting detail organized by schema fields, data types, and query usage. The full data-type enumeration is justified because it directly affects how an agent will interpret fields, though the length keeps it from being maximally 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 output schema, the description takes on the burden of describing return values and does so well: it lists the returned id/name/field definitions, per-field attributes, and data-type semantics. It does not spell out the pagination response shape, but pageSize/pageNumber are already self-described in the schema, so the remaining gap is minor.

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 input schema already documents all four parameters with full descriptions and defaults, so the baseline is 3. The description only restates nameFilter behavior ('Use nameFilter to search for a specific table, or omit it to list all tables') and does not add new parameter-specific meaning; the bulk of its added value is about result-field semantics, not the parameters.

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 opens with a specific verb and resource: 'Discovers tables in the Caspio account along with their field schemas in a single call.' It further distinguishes the resource from sibling tools by calling tables 'the primary data storage objects in Caspio' and enumerating the returned schema, so an agent can recognize it as the table-discovery tool rather than discover_views or discover_directories.

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 provides clear usage context by explaining that the returned id is required by query_table, insert_table_record, update_table_records, delete_table_records, and get_attachment_metadata, and by closing with instructions to use nameFilter or omit it to list all tables. It does not explicitly name sibling discovery tools or give when-not-to-use conditions, so it falls just 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?

Beyond the readOnlyHint and destructiveHint annotations, the description discloses substantial behavior: it returns ids required by several sibling tools, explains editable flags for joined-table fields, specifies boolean encoding for queries, and warns that field name must be used rather than label or tableFieldName. This materially helps the agent understand the tool's outputs and 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?

The description is long but dense and mostly well-structured: purpose, usage rule, return shape, field semantics, data types, and query-naming guidance in order. The data type list is extensive, but since there is no output schema it earns its place; minor redundancy with schema-described nameFilter keeps it from a perfect score.

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?

Because there is no output schema, the description carries the full burden of explaining the response, and it does so in detail: view id, name, field definitions, per-field properties, the meaning of editable=false, and data type encodings. It also connects the returned id to the sibling data-manipulation tools, making it easy for an agent to chain calls 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?

The input schema already has 100% parameter coverage, so the baseline is 3. The description adds a little by restating the nameFilter behavior and the 'omit to list all views' option, but it does not elaborate beyond the schema on pageSize, pageNumber, or includeTriggeredActions.

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 opens with a specific verb and resource: 'Discovers views in the Caspio account along with their field schemas in a single call.' It clearly distinguishes views from tables and directories, and the statement that views can join multiple tables separates this tool from discover_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?

It explicitly gives the selection rule: 'use views when the user's request aligns with an existing view or when the needed data spans multiple tables.' It also explains that tables are the primary data objects, implying when not to prefer views, and gives concrete guidance on using nameFilter versus omitting it.

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 and destructiveHint=false, so the agent knows this is a safe read operation. The description adds context about the returned fields and the note that a table record can have multiple Attachment-type fields, but it does not disclose any additional behavioral traits such as pagination, limits, or error conditions. Given the annotations cover the safety profile, a 3 is appropriate.

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 concise and well-structured: the first sentence states the purpose and lists the returned fields, the second clarifies the optional WHERE clause and notes the multiple-attachment-field aspect. There is no fluff, and all sentences contribute to the agent's understanding. It is appropriately front-loaded.

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 simple read-only metadata retrieval tool with no output schema, the description is mostly complete. It lists all returned fields, explains the optional filter, and clarifies that a record can have multiple attachment fields. It does not explicitly state behavior for multiple files per field or any limits, but these are minor omissions given the simplicity and the annotations that already cover safety.

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 input schema has 100% description coverage, with each parameter (tableId, attachmentFieldName, where) already explained, including examples for the WHERE clause. The description reinforces the use of WHERE for filtering but does not add substantive meaning beyond the schema. Since the schema carries the full burden, the description adds only marginal value, justifying the baseline 3.

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 tool returns metadata for files in an Attachment-type field of a Caspio table, listing specific fields (PK_ID, FileName, etc.). It is specific and unambiguous, but it does not explicitly differentiate itself from the sibling tool get_file_metadata, which could also return file metadata. Thus it is clear but lacks explicit 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 provides no guidance on when to use this tool versus alternatives such as get_file_metadata, query_table, or search_files. It only mentions the optional WHERE clause for filtering, which is about parameter usage, not about choosing the right tool. There is no mention of when not to use it or which scenarios call for a different tool.

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 signal read-only/non-destructive behavior; the description adds useful transparency by listing the exact returned fields and revealing that ExternalKey is an internal GUID. It also clarifies path format and source, which are behavioral context not present in annotations. No contradiction.

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 sentences: the first states the operation, the second enumerates returned fields, and the third explains path provenance. Every sentence earns its place and there is no 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 single-parameter read-only metadata lookup, the description is complete: it names the required input format, gives examples, and lists the return fields, compensating for the missing output schema. It does not need to explain error behavior for this simple operation.

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 both the schema and description give the same leading-slash '/photos/logo.jpg' examples. The description adds the source (File-type field value) but largely reinforces, rather than extends, the schema.

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?

Description opens with a specific verb and resource: 'Returns metadata for a file in Caspio's file system' and names the key fields returned, including ExternalKey. This makes the tool's scope clear and separates it from general search/discovery siblings, even without naming get_attachment_metadata explicitly.

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 guidance on input provenance: the file path must come from a File-type field value, with slash examples. It does not explicitly spell out when to prefer this over get_attachment_metadata or search_files, but the path-source context is clear enough for most selection decisions.

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=false and destructiveHint=false, so the description adds value by explaining the return payload (full created record including PK_ID) and the constraint that auto-generated fields must be excluded. It does not cover error cases or idempotency, but the key behavioral traits are disclosed beyond 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?

The description is moderately long, but every sentence serves a purpose: the first sentence states the action, the second gives the example and format, the third lists exclusions, and the fourth covers case-insensitivity and the discover_tables prerequisite. It is front-loaded and free of filler, though slightly verbose.

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 tool with two parameters, no output schema, and a write operation, this description is complete. It covers the payload format, required field sourcing, editable-field restrictions, return value, and the critical dependency on discover_tables. An agent has everything needed to call it correctly without guessing.

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%, yet the description still adds substantial meaning: it clarifies payload is a flat JSON object, provides an example, states field names are case-insensitive, mandates the source of field names (discover_tables), and specifies which fields must not be included. This goes far beyond the schema's property descriptions.

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 ('inserts') and resource ('a record into a Caspio table'), and explicitly contrasts with view insertion by naming the target as a 'table'. This clearly distinguishes it from insert_view_record and update/delete siblings without needing to open schemas.

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 explicit when-to-use guidance: call discover_tables first for any undiscovered table, and never guess field names. It also details constraints (only editable fields, exclude auto-generated) and explains the tableId parameter must come from discover_tables. This is actionable and prevents common mistakes.

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 state readOnlyHint=false and destructiveHint=false, so the description carries much of the behavioral burden. It exceeds that burden by disclosing the return value ('Returns the full created record including PK_ID'), case-insensitivity of field names, the editable-field restriction, and the prohibition on auto-generated fields. It does not cover auth or failure behavior, but it does not contradict 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?

The description is longer than average, but every sentence carries operational value: purpose, payload shape, editable-field constraints, exclusions, return behavior, and discovery prerequisite. The main action is front-loaded, and the density is justified by the complexity of Caspio view insertion. There is no filler or redundancy.

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 write tool with no output schema and a nested payload parameter, this description is remarkably complete. It explains what the tool returns, how to obtain the viewId, what field names are valid, which fields must be omitted, and how editable fields are determined in multi-table views. An agent has all the information needed to invoke the tool successfully in the normal flow.

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, but the description significantly extends the schema. It clarifies that the payload must be a flat JSON object, gives an explicit example, warns to only include editable fields, lists the auto-generated field types to exclude, and states that field names are case-insensitive and must come from discover_views. This materially improves an agent's ability to construct a valid payload.

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 opens with a clear verb-resource pair: 'Inserts a single record through a Caspio view.' It distinguishes itself from sibling insert_table_record by emphasizing view-specific behavior, and it reinforces the view context with viewId sourced from discover_views. This is specific enough for an agent to know exactly what the tool does and how it differs from nearby tools.

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 explicit prerequisites and workflow: call discover_views first for any undiscovered view, obtain viewId, and confirm editable fields. It also states what not to include (auto-generated fields) and which fields are editable in multi-table views. It does not explicitly name insert_table_record as the alternative for table targets, but the 'through a Caspio view' wording and sibling list make the context clear without exclusion guidance.

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?

With annotations already declaring readOnlyHint=true and openWorldHint=true, the description adds value beyond annotations by clarifying the exact return scope (directory-designated fields plus three enumerated system attributes), the allowed clauses for these attributes, and the critical warning that field names are case-insensitive and must come from discover_directories – never guessed. No contradiction with 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?

The description is a single paragraph but front-loads the core purpose ('Queries users from a Caspio directory') and then adds necessary context in a logical order: directory definition, return fields, attribute details, alternative tool, and a safety warning. It is slightly verbose but every sentence carries useful information; the ALL-CAPS warning ensures the most critical instruction is noticed.

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 read-only tool with no output schema, the description covers the unique aspects that an agent needs: the three system attributes and their possible values, the prerequisite discovery step, and the alternative path for additional fields. Pagination and default limits are documented in the input schema, so they need not be repeated. Overall, an agent is well-equipped to invoke this tool 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 coverage is 100%, so baseline is 3. The description adds extra meaning: it explains that directoryId is obtained from discover_directories and that 'the directory's name has no meaning for API calls'; it lists which system attributes can appear in SELECT/WHERE/ORDER BY/GROUP BY; and it warns against guessing field names. This goes beyond the schema's per-parameter documentation and compensates where the schema can't convey cross-parameter constraints.

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 opens with 'Queries users from a Caspio directory' – a specific verb+resource combination. It goes beyond by stating what it returns ('only the directory-designated fields plus three system attributes not available through regular table queries'), which distinguishes it from query_table. This explicitly differentiates the tool from siblings like query_table and query_view.

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 explicitly tells when to use this tool versus query_table: 'The underlying table may contain additional fields ... that are only accessible through query_table using that table's Id (from discover_tables).' It also mandates a prerequisite for any undiscovered directory: 'Call discover_directories first for any directory not already discovered earlier in this conversation to get its directoryId.' This is model usage guidance.

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 readOnlyHint/openWorldHint/destructiveHint annotations, the description discloses the JSON output shape, pagination metadata, the 1000-record cap, the default of 100, case-insensitive field lookups, and the requirement to source field names from discover_tables. This is substantial behavioral context.

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 dense but each sentence carries load: operation, SQL dialect, return shape, limits, pagination strategy, and a highlighted prerequisite. The most important fact (what it does) is front-loaded.

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 sufficiently documents the return structure and pagination metadata. It also covers the necessary prerequisite (discover_tables), query syntax, and boundary conditions, so an agent has what it needs to invoke the tool 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?

Although schema coverage is 100%, the description adds crucial semantics: pagination defaults and cap, getPaginationInfo's effect, tableId provenance, and especially the rule that field names must come from discover_tables rather than labels. These are not inferable from property descriptions alone.

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 opens with a specific action and resource: 'Queries records from a Caspio table,' and clarifies the return shape. It does not explicitly contrast with sibling query_view or other record tools, though the table-vs-view resource distinction is implicit in the wording.

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 clear operational guidance: call discover_tables first to get a tableId, never guess field names, and paginate with pageNumber/pageSize for result sets over 1000. It does not state when to prefer query_view or other siblings, so it stops short of explicit when-not/alternative routing.

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 and destructiveHint=false, so the safety profile is covered. The description adds substantial behavioral detail: return shape ('records' array of flat key-value objects), pagination metadata behavior, maximum/default record counts, SQL syntax support, case-insensitive field names, and the discover_views prerequisite. This goes well 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?

The description is dense but well-organized: it opens with the core purpose, then covers output format, limits, pagination, and ends with the critical prerequisite. Every sentence contributes operational value, and the IMPORTANT warning is appropriately highlighted.

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 SQL-like query tool with nine parameters and no output schema, the description is remarkably complete. It explains the return structure, pagination metadata, record limits, SQL syntax, field-name sourcing, and the discover_views prerequisite. Nothing essential for correctly invoking the tool 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% with detailed per-parameter descriptions, so the baseline is 3. The description adds meaningful cross-parameter guidance: field names must come from discover_views' field list, viewId is required rather than the view name, and pagination semantics tie pageNumber/pageSize to larger result sets. This enhances parameter understanding beyond the schema.

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 a specific action ('Queries records') and resource ('Caspio view') and explains what a view is. It does not explicitly differentiate query_view from its sibling query_table, so an agent must infer the distinction from the tool names and the view/table framing.

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 concrete usage context: call discover_views first, use pagination for large result sets, and avoid guessing field names. It does not explicitly say when to prefer query_view over query_table or other siblings, but the view-versus-table distinction is clear enough from the opening sentence.

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 establish that this is read-only and non-destructive, and the description adds useful behavioral context by disclosing the exact metadata fields returned and how they can be consumed by other tools. It does not contradict the annotations, though it does omit details like pagination behavior, which the schema already covers.

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, with the primary action and return metadata front-loaded, followed by a concise usage rule. Each clause earns its place without redundancy.

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?

The description covers purpose, return metadata, and when to use it, while the schema covers parameter meanings and defaults. The only notable gap is that 'by name' implies the name parameter is required, yet the schema marks it optional, leaving the behavior when name is omitted unspecified.

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 all five parameters. The description only reinforces the 'name' filter and does not add new parameter-level meaning, which is acceptable given the baseline.

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 states a specific verb and resource ('searches for files in Caspio's file system by name') and declares the output shape (metadata: path, name, size, content type, dates). It also separates itself from sibling tools by describing how results connect to get_file_metadata or download_file, making its role clear.

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 explicitly says when to use the tool: 'find a file when the exact path isn't already known' and gives a concrete trigger (a File-type field value). It names the downstream alternatives (get_file_metadata, download_file), implying that when the path is known, those should be used instead.

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 readOnlyHint=false and destructiveHint=false, which is minimal. The description adds substantial behavioral context: broad WHERE clauses update all matching records (with a caution), partial updates leave omitted fields unchanged, field names are case-insensitive, and the tableId must be the ID not the name. This fully compensates for the sparse 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?

Every sentence earns its place. The description is front-loaded with the primary action, then covers payload format, WHERE behavior, caution, return, and field-name sourcing in a logical order. It is long but not verbose; no filler or repetition.

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 mutation tool with three required parameters, a nested payload, no output schema, and no annotation-provided safety details, this description is remarkably complete. It explains prerequisites (discover_tables), the source of valid field names, the risk of broad WHERE, return behavior, and the meaning of tableId. An agent has everything needed to invoke 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 coverage is 100%, but the description adds meaning beyond the schema: it clarifies that WHERE is required and supports MS SQL syntax, that the payload should contain only fields to update, and that tableId is the API ID, not the table name. These are critical details an agent needs to call the tool correctly, going well beyond the schema's baseline descriptions.

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 states a specific verb ('Updates'), resource ('Caspio table'), and scope ('match the WHERE clause'). It clearly distinguishes from siblings like update_view_records, insert_table_record, and delete_table_records by consistently referencing 'table' and describing update semantics. The return behavior ('Returns all updated records') adds further specificity.

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 clear context on when to use the tool (updating table records) and gives actionable guidance: filter by PK_ID for a single record, call discover_tables first to obtain tableId, and never guess field names. It implicitly separates from view updates by focusing on tables, but it does not explicitly name alternatives or state when NOT to use this tool, so it falls 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?

Beyond the annotations, the description discloses several important behaviors: fields absent from the payload are left unchanged, only primary-table fields are updatable in multi-table views, field names are case-insensitive, broad WHERE clauses update many records, and the tool returns all updated records. This is substantial behavioral context the schema and annotations do not provide.

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 dense but every sentence earns its place. It front-loads the core behavior, then adds warnings about broad updates, primary-table constraints, and the need to discover views before calling. No redundant phrasing or filler is present.

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 has three fully documented parameters, no output schema, and moderate complexity, the description is complete. It covers prerequisites, parameter semantics, record-selection behavior, a critical multi-table constraint, and return behavior. An agent has enough information to call the tool correctly without additional lookup.

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?

Even though the input schema already documents all three parameters, the description adds critical meaning: the payload must be a flat JSON object, omitted fields remain unchanged, WHERE supports MS SQL Server syntax, and field names must come from discover_views rather than being guessed. These additions go far beyond the schema's property descriptions.

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 states a specific verb (updates), a resource (records through a Caspio view), and a precise mechanism (matching the WHERE clause). The phrase 'through a Caspio view' and reference to discover_views clearly differentiate it from table-level operations and view insert/delete 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?

The description gives clear operational guidance: WHERE is required, broad WHERE updates all matching records, single-record updates should filter by a unique field, and discover_views must be called first for undiscovered views. It does not explicitly exclude alternatives like update_table_records, but the context is strong enough for an agent to select this tool correctly.

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