Knack MCP by usefulapi

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

Annotations carry destructiveHint=true, so the description need not restate mutation risk, yet it adds real value: the 'MUTATES' signal, the read-only restriction on Auto Increment/Formula/Equation fields, and the fact that it returns the created record. It stops short of disclosing validation failure behavior or side effects on linked objects.

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?

Four tight sentences, front-loaded with the 'MUTATES' signal and the core action. The endpoint detail is borderline but useful for disambiguation; nothing is 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?

With no output schema, the description compensates by noting it 'Returns the created record', and it covers the read-only-field constraint. It could say more about objectKey sourcing or required permissions, but an agent has enough 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?

Schema description coverage is 100%, so the schema already documents both objectKey and fields. The description restates the fields example verbatim rather than adding syntax or edge-case guidance beyond the schema, so 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?

The description states a specific verb+resource ('creates a new record in an object') and even names the underlying endpoint POST /objects/{object_key}/records. This clearly distinguishes it from siblings like knack_update_record and knack_delete_record without opening any 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 'MUTATES Knack data' framing and the create verb imply when to use it, but no explicit condition for choosing this over knack_update_record or knack_request is given. Usage is implied 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 declare destructiveHint=true, so the safety profile is partly covered, but the description adds real value: it stresses the deletion is permanent/irreversible, names the underlying endpoint, and documents the success return shape ({ delete: true }). It stops short of mentioning permissions or error/failure behavior.

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 compact sentences with no waste; the mutating/irreversible nature is front-loaded, followed by the endpoint and return contract. Every sentence 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?

For a simple two-parameter destructive tool with no output schema, the description covers the essential: what it destroys, irreversibility, the API mapping, and the return value. It lacks only failure-mode and permission context, a minor gap given annotation coverage.

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 both parameters (recordId, objectKey) are documented with examples in the schema. The description adds no parameter-level meaning beyond what the schema already provides, 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 and resource ('permanently DELETES a record') plus the exact API endpoint, so the agent knows precisely what operation this performs. It is clearly distinguishable from the sibling create/update/get/list record 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 never says when to choose this tool over alternatives. With siblings like knack_request (arbitrary API calls) and knack_update_record, the agent gets no guidance on routing, no prerequisites, and no warnings about what must be true before deleting.

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?

readOnlyHint already declares this is a safe read. The description adds genuinely useful context beyond that: the response is the raw JSON 'as-is' (important since no output schema exists) and app_id silently falls back to the configured KNACK_APPLICATION_ID. It does not mention rate limits or error behavior, but for a passive GET this is solid.

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 compact sentences; the resource and its contents come first, then the endpoint, then the default-behavior note. No filler and nothing important buried.

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 describing the return value and does so ('full schema/metadata — objects, fields, scenes', raw JSON as-is). Combined with 100% parameter coverage and a read-only annotation, an agent has everything needed 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?

Schema description coverage is 100% and the single optional parameter is fully documented in the schema. The description's note that app_id defaults to KNACK_APPLICATION_ID largely restates the schema, adding no format or validation detail. 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 ('Fetch') and resource ('a Knack application's full schema/metadata') and enumerates contents (objects/tables, fields, scenes). The inclusion of the underlying endpoint GET /applications/{app_id} pins down exactly which resource is retrieved, distinguishing it from the record- and field-level 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 implies when to use it (when you need the whole schema at once) by stating it returns objects, fields and scenes together, but it never explicitly contrasts this with knack_list_objects or knack_list_fields, which are the obvious alternatives. 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, so the safety profile is covered. The description adds real value beyond that by disclosing the return shape ('bare record (with both field_x and field_x_raw values)'), which matters since no output schema exists. It does not cover error behavior for a missing id, keeping it short of a 5.

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 with zero filler; the core purpose is front-loaded before the endpoint and return detail. Every sentence carries distinct 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?

For a simple two-parameter read tool with annotations covering safety and a description covering the return shape, the definition is essentially complete. Missing only minor operational detail such as not-found behavior, which is a small gap rather than a real omission.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so both parameters are already documented (recordId as a hex string, objectKey as e.g. "object_1"). The description restates these in the endpoint template but adds no format, validation, or constraint detail beyond the schema, so 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 and resource ('Fetch a single record by id') and includes the exact API endpoint, which pins down semantics. 'Single record' implicitly distinguishes it from the sibling knack_list_records, though no sibling is named 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?

Usage is only implied: an agent infers it should call this when it already has an objectKey and recordId. There is no explicit when-to-use, no exclusion for bulk retrieval (knack_list_records), and no guidance on when to prefer the generic knack_request.

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, so the safety profile is covered. The description goes beyond that by disclosing the underlying call (GET /applications/{app_id}), the client-side filtering on key === objectKey, and the app_id default, which materially helps an agent predict behavior.

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 with the return shape front-loaded and the fetch/filter mechanism second. 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?

There is no output schema, but the description supplies the return shape and the filtering semantics, and it covers the only non-obvious parameter behavior (app_id default). Nothing an agent needs to call this 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 parameters are already documented. The description restates the appId default and the 'object_1' example, adding no syntax or constraints beyond the schema, 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 and resource ('List the fields of ONE object') and even specifies the exact return shape [{ key, name, type, required }]. The emphasis on 'ONE object' plus the API path implicitly separates it from knack_list_objects and knack_get_application.

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 scope restriction ('ONE object') and the objectKey example imply the intended use case, but there is no explicit when-to-use guidance and no mention of when to prefer knack_get_application or knack_list_objects instead. Usage is inferable but not 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?

The readOnlyHint annotation already establishes this as a safe read, so the bar is lower. The description adds useful context: it discloses the exact return shape and the fallback behavior for app_id, but says nothing about ordering, empty-application behavior, or whether listing is complete for large applications.

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 with zero filler. The return shape is front-loaded and the default-value note is appended where it is most useful.

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, and the description compensates by specifying the returned array shape and its fields. For a single-optional-parameter read tool, nothing an agent needs in order to invoke 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 schema already documents the appId default, so the description largely restates it. Baseline 3 applies when the schema does the heavy lifting and the description adds no syntax or format detail beyond it.

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 an application's objects (tables)') and clarifies the Knack-specific terminology by equating objects with tables. It does not explicitly contrast itself with closest siblings like knack_get_application or knack_list_fields, but the stated compact-array scope implicitly separates it from both.

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?

'Convenience over GET /applications/{app_id}' implies the usage context (a lightweight alternative to the raw API call), but it never states when to prefer knack_get_application or knack_list_fields. The guidance is inferable rather than explicit.

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=true, so the description adds real value: it discloses the exact return envelope shape, notes values come in both formatted (field_x) and structured (field_x_raw) forms, and states the rows_per_page ceiling of 1000. It omits auth/rate-limit context, keeping it short of a 5.

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 dense sentences, front-loaded with purpose then return shape then the paging/sort/filter controls. No filler, though the endpoint string and envelope body are somewhat compressed.

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 compensates by describing the paged envelope and the dual formatted/raw value convention, which is the key thing an agent must anticipate. For a 6-param nested-filter tool it is nearly complete, missing only error/failure behavior.

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%, including the filters shape and operator list, so the baseline is 3. The description's parameter mentions (page, rows_per_page, sort_field, sort_order, filters) largely restate the schema and add only the max-1000 reminder.

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 an object's records') and pins it to the underlying endpoint GET /objects/{object_key}/records. This clearly separates it from knack_get_record (single record) and the other siblings without ambiguity.

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 explains how to page, sort, and filter, which is operational guidance, but never says when to prefer this tool over alternatives such as knack_request or knack_get_record for a single record. Usage is implied rather than routed.

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, so the safety profile is known; the description reinforces this and adds the useful constraint that only GET is permitted (no POST/PUT/DELETE). It does not disclose auth requirements, rate limits, or how errors/raw payloads come back, so with annotations carrying the main burden 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?

Three short sentences, front-loaded with the tool's role, then the safety constraint, then the path format. No sentence is redundant or padded.

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 raw pass-through GET with no output schema, the description covers the essentials: what it does, the read-only constraint, and the path format. The unavoidable unknown (arbitrary response shape) is inherent to a raw API escape hatch, so little 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 parameters are already documented in the schema. The description repeats the leading-slash path format with an example but says nothing about the optional 'query' object, adding no meaning beyond the schema — 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?

States a specific verb (GET) and resource (any Knack API path), and explicitly scopes it to paths 'not wrapped by a dedicated tool'. An agent can distinguish this from knack_get_record or knack_list_records without opening any schema, since the escape-hatch role is stated outright.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives a clear usage context ('power-user escape hatch') and an exclusion condition — use it only for paths not covered by a dedicated tool — with 'view-based reads' as a concrete example. It stops short of naming the specific sibling tools to prefer, so routing is slightly inferential rather than explicit.

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 supply a blunt destructiveHint=true; the description usefully refines this by clarifying that it is a partial update (only included fields change) and that Auto Increment / Formula / Equation fields are read-only, plus it states the return ('the updated record'). It stops short of covering permissions, rate limits, or error behavior for nonexistent records.

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 critical fact ('MUTATES Knack data') in the first clause and keeps the four sentences tight. The read-only field warning and the `fields` keying example are each stated twice (description and schema), which is mild 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?

With no output schema, the description correctly states that the updated record is returned, and it covers the mutation semantics and write-restricted field types. It omits what happens on invalid record ids or partial failures, which would matter for a destructive PUT.

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 all three parameters are documented in the schema with examples, so the baseline is 3. The description's example of `fields` keying largely repeats the schema's own example and the read-only warning, adding little beyond structured data.

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 ('updates a record' on Knack data) and even names the underlying API call (PUT /objects/{object_key}/records/{record_id}), which cleanly separates it from knack_create_record, knack_delete_record and knack_get_record. An agent can identify the operation 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?

The description implies usage by explaining that only included fields change, which is useful partial-update guidance, but it never says when to prefer this over siblings such as knack_request or how it differs from a full replace. No exclusions or alternatives are named, so the agent must infer the routing.

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