Rowflare

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds real behavioral context: computation happens in the database, multi-value fields count a record once per value, and date grouping defaults to day with week/month/year bucketing.

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 dense sentences, front-loaded with what it does and why to use it, then edge-case semantics. No redundant filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

No output schema exists, yet the description never describes the result shape (metric keys, grouped row structure) or how filter interacts with the aggregation. For a 7-parameter nested tool, it covers the core but leaves notable gaps.

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 only 43%, so the schema alone does not fully document parameters. The description clarifies groupBy cardinality, bucket options, and date semantics, but says nothing about as, filter, view, or timezone, leaving several parameters reliant on sparse schema text.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb set (count, total, average, min, max) and resource (table), plus scope details: grouped by up to 2 fields, computed in the database. This clearly separates it from record-reading siblings like get_records/query_records.

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

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

Explicitly says to use this instead of reading all records when answering how many / how much questions, which names the alternative approach. It does not spell out when-not conditions (e.g. when raw rows are actually needed), but the routing guidance 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 declare this as a non-readonly, non-destructive, non-idempotent, open-world write. The description adds a genuinely non-obvious behavioral fact not in the annotations: the automation is created switched off unless enabled is true. It does not cover side effects like whether it begins firing immediately or any permission requirements.

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 compact paragraph where nearly every clause carries information — no filler or restatement of the name. Readability would improve if the trigger, step and template lists were separated rather than run together with colons and commas.

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 deeply nested 5-parameter tool with no output schema, the description covers the enum domains and template syntax well but leaves meaningful gaps: what is returned on creation (an automation id?), how step fields map to step types (createRecord needs table+values, http needs url+method), and the branch one-level nesting constraint is mentioned but its then/else shape is not tied to the 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?

Top-level schema coverage is 0%, so the description carries real weight: it defines the trigger taxonomy, the step taxonomy and ordering, the branch nesting limit, and a full template namespace ({{trigger.record.<Field>}}, {{steps.<id>.records[0].<Field>}}, {{now}}, etc.) that appears nowhere in the schema. It does not clarify baseId/name/enabled semantics beyond the default-off note, and it omits which fields each step type requires.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

Opens with a specific verb+resource ('Create an automation from a trigger and steps') and immediately names the two structural inputs. It enumerates every allowed trigger and step type, so an agent knows exactly what it is building. It stops short of naming update_automation/get_automation as the alternatives, so sibling differentiation relies on the tool name alone.

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 construction-level guidance (steps run in order, branch is one level deep with then/else, automations start disabled), which shapes correct invocation. However there is no explicit when-to-use/when-not guidance versus update_automation or list_automations, and no stated prerequisite that ai steps need a service id from list_ai_services.

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, idempotentHint=false, and destructiveHint=false, so the mutation/safety profile is covered. The description adds useful behavioral defaults beyond annotations, including automatic stacking for widgets without positions and monthly date bucketing unless overridden.

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 create action and then spends its space on the complex widget model. It is dense but appropriately sized for the widget configuration surface, with little filler.

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 tool is complex due to nested widget configuration, and the description covers widget semantics fairly well. However, it omits core creation context such as what baseId means, whether all widgets are created atomically, and what the tool returns, which matters more because there is no 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?

Top-level schema descriptions are absent for name, baseId, and widgets, so the description must compensate. It explains widget types, grouping fields, metric semantics, and date bucketing well, but does not explain baseId/name or many other widget properties, leaving partial compensation.

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 first sentence clearly states a specific verb and resource: creating a dashboard, optionally with widgets. It does not explicitly differentiate from update_dashboard or get_dashboard, but the create intent is 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 does not say when to use create_dashboard versus update_dashboard, get_dashboard, or list_dashboards, nor does it state prerequisites such as needing an existing base. Usage is implied only by the word 'Create'.

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 establish the mutation profile (readOnlyHint=false, idempotentHint=false), so the description's job is to add context — which it does by disclosing the non-obvious traversal semantics of pathLookup (walks chains to any depth, follows dependsOn direction) and the empty-filter idiom. It does not mention side effects such as a link field creating the reciprocal field in the linked table, which is a meaningful omission for a create operation.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three sentences, front-loaded with the core action before the specialized detail. The pathLookup sentence is long and clause-heavy but every clause carries information an agent would otherwise have to guess.

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 create tool with no output schema and a 20-type nested field object, the description covers the hardest case (pathLookup) but omits the create/update/delete sibling boundaries and what happens on failure or with duplicate names. The rich schema carries most of the remaining burden, so this is adequate but not complete.

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

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

Schema description coverage is 33%, and the nested object is already extremely well documented in the schema itself (every option field carries its own description). The description adds real meaning for targetTable/direction/maxDepth/targetFilter but says nothing about baseId or the top-level field container, and covers only 1 of the 20 enum field types.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

Opens with a specific verb+resource: 'Add a field to a table.' The word 'add' distinguishes it in spirit from update_field and delete_field, and the rest of the description narrows it to a specific field type (pathLookup). It never names a sibling explicitly, so an agent must infer the create-vs-update and create_field-vs-generate_ai_field boundaries.

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 by the description of pathLookup semantics and the empty-filter trick, but there is no explicit 'use this when…' statement, no exclusion of update_field/generate_ai_field, and no mention of prerequisites such as needing an existing table or write permissions.

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, destructiveHint=false, idempotentHint=false. The description adds nothing beyond the batch size already encoded in the schema — no mention of what happens on partial failure, whether the whole batch is atomic, or what identifiers come back. For a bulk mutation, that is a meaningful gap.

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 five-word sentence with zero padding and the key constraint front-loaded, so it is genuinely concise. However, brevity here reads as under-specification rather than disciplined editing — the sentence earns its place but leaves obvious room for one more useful clause.

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?

A non-idempotent bulk-write tool with 4 parameters, an undocumented baseId, no output schema, and no stated return shape. The description covers none of this, so an agent cannot predict the response or the failure semantics from the definition.

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 only 50%, and baseId has no description anywhere, so the description should have compensated but doesn't. It also ignores typecast, whose default-true behavior measurably changes creation outcomes (auto-creating select options, matching linked records by 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 verb+resource (create records) is clear, and the batch range 1-200 adds a concrete scope note. But it does nothing to distinguish this from siblings like create_table or create_field, and the range is already enforced by minItems/maxItems in 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?

There is no guidance on when to use this versus update_records, create_field, or any sibling, and no prerequisites such as required permissions on the base/table. The agent must infer usage entirely from the name.

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 cover the safety profile (mutating, non-destructive, non-idempotent), so the bar is lower. The description still adds genuine behavioral detail not in the annotations: the primary-field type constraint and the ordering dependency rule for link/lookup/rollup/formula fields, plus the exact default field set created when fields is omitted. It does not mention permissions or whether the table can be rolled back.

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 action and then the two constraints that most affect call correctness. The opening 'Create a table.' is essentially a restatement of the title and could be merged, but the rest 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 mutating create tool with a very large nested schema and no output schema, the description covers the highest-risk correctness issues (primary field type, field ordering, defaults) but says nothing about the created table's identifier being returned or required auth/base context. Adequate but with clear gaps given the tool's complexity.

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?

Reported schema coverage is 0% for top-level parameters, so baseId and name get no explanation anywhere. The description does add real meaning for the fields array — primary-field constraint, intra-call reference ordering, and default behavior when empty — which is more than the schema conveys at that level, and the deep nested options carry their own inline 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 and resource ('Create a table') and immediately pins down the field-level semantics, including which field becomes the primary field and how the default field set behaves. It does not explicitly distinguish itself from siblings like create_field or update_table, so an agent must infer the boundary from the name alone.

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: the note about fields referencing fields listed earlier tells the agent how to order a call, and the default-fields sentence tells it what happens if fields is omitted. There is no explicit when-to-use guidance against create_field (adding a field to an existing table) or update_table.

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 annotations declare that this is a non-destructive mutation, and "Add" is consistent with that. The description adds scope about supported view types and optional settings but does not disclose permissions, duplicate-name behavior, failure modes, or other behavioral context 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 a single front-loaded sentence with no wasted clauses. It efficiently lists the view types and optional settings that matter for this creation tool.

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?

This is a complex creation tool with 15 parameters, 47% schema description coverage, and no output schema. The description omits key required parameters and several type-specific parameters, and it provides no usage or permission context, leaving significant gaps for an agent to resolve from the schema alone.

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 only 47% across 15 parameters, so the description should compensate more. It helpfully mentions filter, sort, hidden fields, and type-specific concepts such as grouping, date fields, lanes, and cover, but it omits required targeting parameters like baseId, table, and name, and leaves several optional parameters undocumented.

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 and resource: "Add a ... view." It clearly enumerates supported view types and optional view settings. It does not explicitly distinguish this creation tool from the sibling update_view tool, so it misses full 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 does not say when to use create_view versus update_view, nor does it state prerequisites or when a particular view type is appropriate. Usage is only implied by the word "Add."

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 destructiveHint=true and idempotentHint=true, so the safety profile is covered, but the description adds real value beyond them: deletion is permanent, field values are lost, and deleting a link field cascades to its inverse relation. That cascade consequence is not conveyed anywhere in the structured fields.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two short sentences, zero filler, with the permanence warning front-loaded before the cascade caveat. 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 destructive three-parameter tool with no output schema, the cascade note is the key missing piece and it is present, but the description leaves open whether a field can be addressed by name, whether references in views/formulas break, and what the call returns. Annotations carry the destructive flag, so the gap is moderate rather than severe.

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 only 33% — just 'table' is documented as name-or-id — and the description adds nothing about baseId or whether 'field' accepts a name or only an id. With low coverage the description is expected to compensate, and here it supplies no parameter meaning at all.

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 ('Permanently delete') and resource ('a field and its values'), which distinguishes it from delete_records and delete_table by resource noun alone. It does not explicitly name those siblings, so differentiation is implicit rather than stated.

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?

No guidance on when to use this versus update_field (to clear or retype a field) or delete_table, and no prerequisites or warnings about confirming before a permanent removal. The agent must infer the decision rule from the tool name.

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 destructiveHint=true and idempotentHint=true, so the safety profile is covered. The description adds useful context beyond the annotations by emphasizing 'Permanently' and stating the 1-to-200 batch limit, though it does not mention required permissions or what happens to missing IDs.

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, front-loaded sentence with no filler. Every element ('Permanently', '1 to 200', 'by id') contributes directly to correct invocation.

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, three-parameter mutation tool, the description covers the ID batch constraint but omits how baseId and table scope the deletion. Annotations cover safety, and there is no output schema to explain, but the parameter-level gaps keep it from being complete.

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

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

Schema description coverage is only 33%, with 'baseId' undocumented and 'table' only lightly described. The description adds meaning only for the 'ids' parameter by stating the 1-to-200 range; it does not explain how baseId and table identify the target records.

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 ('delete') and resource ('records'), plus the key scope detail 'by id'. It distinguishes itself from read/query siblings implicitly through the delete verb, but does not explicitly contrast with update_records or delete_field/delete_table.

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

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

There is no explicit guidance on when to use this versus alternatives such as update_records or deleting via other tools. 'By id' hints that the caller must already know record IDs, but this is left implicit rather than stated as a selection condition.

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 destructiveHint=true and idempotentHint=true, so the safety profile is covered. The description adds valuable non-obvious behavior: deletion cascades to records and to link fields in other tables, and the action is permanent. It does not mention permissions or return behavior, but the cascade disclosure is significant.

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 efficient sentence with no waste, front-loading the destructive action and cascade consequences.

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 strong annotations and no output schema, the description covers the essential behavioral facts: permanent deletion plus cascade effects. It leaves baseId semantics and usage alternatives unaddressed, but the core safety context is present.

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 only 50%, and the description explains neither parameter. The schema documents 'table' as name or id, but baseId has no description in either place, so the description fails to compensate for the coverage 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?

Uses a specific verb and resource ('Permanently delete a table') and explicitly states the scope: its records and link fields in other tables. This clearly distinguishes it from delete_records and delete_field.

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 word 'Permanently' implies this is for irreversible removal, but the description gives no explicit when-to-use guidance, prerequisites, or alternatives such as update_table or delete_field. Usage is only implied from the verb and resource.

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 cover the safety profile (readOnly, non-destructive, closed-world), so the description's job is to add context — and it does by disclosing payload contents: fields with type and options, primary field, row count, views. It stops short of noting cost or size for very large bases, which would matter at scale.

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, front-loaded with what is returned, followed by the actionable calling rule. No filler or restatement of the title.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

There is no output schema, and the description compensates by enumerating the return contents precisely enough that an agent knows whether the result answers its question. For a single-parameter read tool, nothing needed for correct invocation 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% and the schema already documents baseId with its provenance ('Base id from list_bases'). The description adds no further parameter meaning, so the baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('show every table in a base') and enumerates exactly what is returned: fields with type and options, primary field, row count, views. This is distinguishable from list_bases (which returns bases, not their interior) and from get_records/query_records.

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

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

Explicitly prescribes timing: 'Call this before reading or writing records so you use the right table and field names.' That is a clear when-to-use condition with a stated rationale, though it doesn't name alternative discovery tools or say when-not to call 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 readOnly=false, openWorld=true, idempotent=false, destructive=false. The description adds genuinely new behavior: generation runs asynchronously in the background and results must be read later, which is essential for an agent to avoid expecting synchronous output. It omits rate limits, expected latency, and whether re-queuing duplicates work.

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?

One tight sentence that front-loads the async nature and the result-retrieval instruction. 'Some records' is a bit vague but nothing is 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?

No output schema exists, yet the description doesn't say what a successful call returns (job id? count?) or how failures surface — and the required baseId/table/field identifiers are unexplained. For an async mutation tool this leaves an agent guessing about the immediate response.

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% across five parameters, so the description must carry the load. It only gestures at two optional params ('some records' → records, 'never generated' → missingOnly) and says nothing about baseId, table, field formats, or the 5000-item cap on records.

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 ('Queue AI generation ... of an AI field') and signals scope modes (some records, missingOnly, whole column), which distinguishes it from sibling mutators like create_field or update_field. It stops short of explicitly naming those siblings as alternatives.

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 three operating modes (records list, missingOnly, whole column) imply when to pick each, but the description never states preconditions — e.g. that the field must already be an AI field, or how to discover AI services via list_ai_services. Usage is inferred 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, idempotentHint and destructiveHint=false, so safety is covered. The description earns credit for disclosing the payload shape beyond annotations: trigger and steps resolved to table/field names, optional webhook URL, and a bounded last-20-runs history, which tells the agent this is a detail fetch with embedded run data rather than a raw config dump.

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 tight sentence with the returned content front-loaded and no filler. It is a grammatical fragment rather than a complete sentence, but nothing 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?

With no output schema, the description must carry the return-value burden and does so partially (trigger, steps, webhook, 20 runs). It leaves out how the two required parameters are used and how this differs from list_automations, which are the main remaining gaps for a 2-param read tool.

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 only 50%: the 'automation' param documents 'name or id' but baseId is undocumented. The description says nothing about either parameter — not that automation accepts a name or id, not that baseId scopes the lookup — so it fails to compensate for the coverage 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?

The description enumerates what comes back (trigger, steps, webhook URL, last 20 runs) which pins the resource to a single automation, but it is a noun phrase with no verb and never distinguishes itself from the closely named sibling list_automations or from update_automation. An agent can roughly infer retrieval, but the intent is implied rather than stated.

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 guidance on when to call this versus list_automations (to discover automations) or update_automation. No prerequisites, no preconditions, no exclusions are mentioned.

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 a read-only, idempotent, non-destructive operation. The description adds useful behavioral detail beyond annotations: it explains what is returned (widget settings and current numbers over all time) and how problem widgets behave (they report the issue and carry no data).

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 two tight sentences with no wasted words. The key return behavior is front-loaded, and the problem-widget behavior is added efficiently.

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 does a reasonable job explaining the return shape and error behavior for problematic widgets. However, it leaves gaps around parameter meaning (especially baseId) and does not clarify lookup failure behavior or the relationship between baseId and dashboard.

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 description does not mention either parameter. Schema coverage is only 50%: the 'dashboard' parameter is described as 'Dashboard name or id', but 'baseId' has no schema description and is not clarified by the tool description. The description therefore does not compensate for the incomplete parameter documentation.

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 communicates that this tool returns a dashboard's widgets, their settings (table and field names), and current values, which implies a single-dashboard retrieval operation. It is distinguishable from list_dashboards and update_dashboard by its focus on widget contents, though it never explicitly states 'retrieves one dashboard' or differentiates itself from 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?

There is no explicit guidance on when to use this tool versus alternatives such as list_dashboards, describe_base, or update_dashboard. Usage is only implied by the content description, and no exclusions or prerequisites are given.

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 safety is covered; the description adds genuinely non-obvious behavior beyond that — text payloads are silently truncated at 2,000 characters unless fullText is set, and the batch size is capped at 100. It does not cover what happens when an id does not exist (error vs omission), which is the main remaining unknown for a read tool.

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 with zero preamble; the size cap and the truncation rule are front-loaded. Every clause carries information the agent could not get from 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?

With rich annotations, only five parameters and no output schema, the description covers the two behaviors an agent would otherwise get wrong (batch cap, text truncation). Gaps remain around baseId's format and the missing-id response, but these are minor for a simple key-based read.

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 only 40% (table and fields documented, baseId/ids/fullText bare), so the description must compensate. It does explain fullText's behavioral effect — the one parameter whose meaning is not evident from a boolean name — but leaves baseId and ids undocumented, so coverage is only 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 (fetch) and resource (records) plus a scope qualifier — retrieval 'by id' capped at 100 — so the agent can infer this is a key-based lookup rather than a filter query. It never names the sibling query_records, so the differentiation is implied by 'by id' rather than stated.

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?

'Fetch ... by id' hints that this is the path when ids are already known, which implies query_records is for filtering, but no when-to-use/when-not-to-use rule or alternative is named. The agent must infer the routing decision from the prepositional phrase alone.

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 openWorldHint=false, so the safety profile is covered. The description adds the scoping fact that results are limited to the base's own workspace, which is genuine context, but it says nothing about return ordering, size, pagination, or what happens when the workspace has no AI services enabled.

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 tight sentence with no filler, and the high-value consumption hint (options.ai.service) is placed inline. The phrasing is somewhat elliptical — a sentence fragment without an explicit verb — but nothing 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?

For a simple one-parameter read tool with no output schema and no nested objects, this is close to sufficient: the agent knows what the call returns in kind and where to use the results. It still leaves the parameter unnamed and gives no sense of the returned fields (id, name), which matters for a tool whose whole purpose is feeding IDs into other calls.

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% and the sole required parameter, baseId, is never mentioned by name in the description. The phrase 'of the base's workspace' only obliquely implies that the base scopes the result set; an agent gets no confirmation that baseId is the selector or what the accepted identifier format is.

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 the resource precisely — model services of the base's workspace — and adds where those values are consumed (options.ai.service and AI automation steps), which makes the payload's purpose unmistakable. It lacks an explicit 'List' verb in prose, but the resource plus the name make the operation clear and distinct from siblings like list_automations or describe_base.

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: the mention of 'options.ai.service' and 'AI automation steps' suggests calling it to discover valid service identifiers before configuring an AI field or automation, but there is no explicit when-to-use, no prerequisites, and no named alternative among the 25 siblings.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds genuinely new behavioral context beyond that: the permission gate (editors/owners) and the shape of each record (trigger type, on/off state, last run), which tells the agent what it will actually see.

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, no filler. The returned-field summary is front-loaded and the access restriction follows it, so the agent gets the substance before the caveat.

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 tool with full annotation coverage and no output schema, the description supplies the essentials: what is listed, what each entry contains, and who may call it. Only the pagination/result-size question goes unanswered, which is a minor gap at this complexity level.

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 baseId parameter is undocumented in the schema. The phrase "of a base" does imply that baseId identifies the target base, but the description adds nothing about format, accepted ID types, or behavior for an invalid base — the minimum compensation needed at this coverage 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 the resource (automations of a base) and enumerates what each entry includes: trigger type, enabled status, and last run. It implicitly distinguishes itself from the singular get_automation by being a bulk listing, but never says so explicitly, so sibling differentiation is left to inference.

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?

"Editors and owners only" gives an access prerequisite, which is useful context for when the call will succeed. However, there is no explicit guidance on when to use this versus get_automation or update_automation, and no mention of pagination or volume expectations for a list operation.

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 this is a read-only, non-destructive, closed-world operation. The description adds useful return context by saying results include workspace and the caller's permission level, though it does not discuss ordering, empty results, or pagination 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?

It is a single front-loaded sentence with no wasted words. The key action and scope are stated first, followed by the useful result attributes.

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 list tool with rich safety annotations and no output schema, the description gives enough context to understand what it returns. Minor omissions such as ordering or empty-state behavior keep it from being fully complete.

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

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

The tool takes zero parameters, so there are no parameter semantics to explain. The baseline for a zero-parameter tool is 4, and the description adds no misleading parameter information.

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: 'List the Rowflare bases you can access.' It also clarifies the returned context, workspace and permission, but does not explicitly distinguish this from the sibling tool describe_base.

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 phrase 'you can access' implies this is a discovery tool, but the description never states when to use it rather than describe_base or other base-related siblings. Usage is inferable but not explicitly guided.

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

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

Annotations already declare readOnly, idempotent, non-destructive, closed-world, so the safety profile is fully covered. The description adds one useful behavioral detail: each returned dashboard includes its widget count. It says nothing about ordering, pagination, or whether an empty base returns an empty array.

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?

Extremely short and front-loaded, zero filler. However, it is a sentence fragment rather than a statement of action, which slightly undercuts clarity for such brevity.

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 bears full responsibility for describing the return value, and only 'widget counts' is disclosed — nothing about other dashboard fields, result shape, or ordering. For a listing tool with a 0%-documented required parameter, this is under-specified.

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 0%, so the description must carry the weight; 'of a base' at least tells the agent baseId scopes the listing, but there is no mention of the ID format or whether it is required. Marginal compensation for the coverage 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?

The fragment names the resource (dashboards) and scopes it to a base, plus mentions widget counts. But it omits a verb like 'list/return' and gives no signal distinguishing it from the sibling get_dashboard or create_dashboard beyond the name.

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?

No indication of when to use this versus get_dashboard for a single dashboard, or versus describe_base for base structure. The agent must infer from the tool name alone.

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

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

Annotations already declare readOnly/destructive/openWorld, so the safety profile is covered; the description adds genuinely non-structured behavior: that view filters and sorts are implicitly applied and that filter narrows rather than overrides them, plus that results carry total and nextOffset for paging. It does not discuss the limit/offset interaction or any truncation behavior, which is the main remaining gap.

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 tight sentences, each earning its place: capability, mechanism selection plus view interaction, then return shape. The performance hint is front-loaded inline with the parameter names rather than 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?

For a 9-parameter read tool with nested filter objects and no output schema, the description covers the semantics an agent most needs (filter vs formula, view interaction, paging). Missing sort/field-projection guidance and the absence of any return-shape note beyond total/nextOffset keep it from being complete.

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

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

With schema coverage at 56% and nine parameters, the description compensates meaningfully: it explains the filter-vs-formula semantic split, supplies a concrete Airtable formula example for the otherwise undescribed formula parameter, and clarifies offset via 'nextOffset for paging'. Sort, baseId, and the filter conjunction remain unexplained anywhere, so it is strong but not complete.

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 ('Find records in a table') and immediately scopes how matching works. It is clear against write-oriented siblings like create_records/delete_records, but it never distinguishes itself from get_records, which likely fetches by id, so an agent must infer the boundary.

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 concrete selection guidance between the two query mechanisms: 'filter (structured, fast)' vs 'formula (... slower)', which is exactly the decision an agent faces. It also explains the view interaction rule ('the view's own filters and sorts apply and filter narrows them'). It does not name a sibling alternative or a when-not-to-use case, 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 it is a non-read-only, non-destructive, non-idempotent, open-world mutation, so the description's contribution is the whole-replacement semantics for trigger/steps plus the supported template vocabulary - both are real behavioral facts not present in structured fields. It still omits whether unmentioned fields are preserved and what the call returns.

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, front-loaded with the four actions an agent can perform, followed by one dense but high-value reference list. No filler, no restatement of the tool name or title.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a nested, open-world mutation with no output schema, the definition still leaves gaps: baseId is undocumented, the return value is never described, and the conditions under which the template list applies (values/body/prompt/filter) are left implicit. Adequate to call it, but not complete.

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

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

With schema coverage at only 17%, the description compensates well at the top level: name = rename, enabled = on/off, trigger and steps = whole replacement, and the template list supplies the substitution syntax ({{steps.<id>...}}, {{trigger.record.<Field>}}) that the schema never states. The required baseId parameter remains entirely unexplained in both description and schema, and the template list is undifferentiated rather than mapped to specific fields.

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 specific verbs and enumerates exactly what can be mutated: rename (name), switch on/off (enabled), replace trigger, replace steps. That maps cleanly onto the mutation parameters and distinguishes it from read-oriented siblings like get_automation/list_automations without naming them 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?

The parenthetical '(each is replaced as a whole when given)' is a useful usage cue for trigger and steps, implying omitted fields are left alone and that a single-step edit requires resubmitting the whole array. However, there is no explicit when-to-use guidance, no mention of reading current state with get_automation first, and no comparison to create_automation.

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 the generic safety profile (readOnly=false, destructive=false, idempotent=false), and the description adds real behavioral detail: name validation occurs before any write, and the four operation kinds are applied in a fixed order (rename, remove, update, add). It stops short of stating permission requirements or whether a removed widget can be recovered, which matters for the remove path.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three sentences, no filler, front-loaded with the primary purpose and then the operational semantics. The ordering rule is stated once and compactly rather than expanded into prose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with nested widget arrays, no output schema, and mutation semantics, the description covers the essentials an agent needs: partial updates, id source, layout semantics, validation-before-write, and write ordering. It leaves gaps around failure behavior (duplicate names, name collisions on rename) and what an empty result looks like.

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 only 33%, so the description has to carry weight, and it does explain the key semantic: update entries key off a widget id and are partial, and position moves or resizes. It says nothing about baseId, dashboard, or the distinction between remove and add entry shapes, leaving three of six top-level parameters supported only by 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 states a specific verb and resource ('Rename a dashboard') and enumerates the full operation set: add, change, move, remove widgets. That distinguishes it cleanly from create_dashboard, get_dashboard and list_dashboards without needing to name 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?

It gives concrete usage context: widget ids come from get_dashboard, and 'only the settings you pass change' tells the agent this is a patch-style update rather than a full replace. It never names an alternative tool or an explicit when-not-to-use case, which keeps it 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 flag destructiveHint=true and idempotentHint=false, and the description goes beyond that by spelling out the actual data-loss semantics: omitted options are removed from cells and a type change converts every cell. That is exactly the risk context an agent needs before invoking a destructive tool.

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 tight sentences, front-loaded with the operation, then the destructive select-option rules, then the type-conversion warning. Every sentence carries behavioral information with no filler.

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 mutation tool with nested options and no output schema, the description covers the main hazards (option removal, type conversion). It leaves out permission requirements and how renaming/type changes affect existing cell values, which would round it out.

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 only 29%, so the description must compensate. It does explain the tricky `options` semantics (full list required, renameFrom, omission removes cells), but it says nothing about baseId, name, description, or the type enum's conversion behavior beyond one sentence.

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 concrete verbs and resource: 'Rename a field, change its type or options, or set its description.' This distinguishes it clearly from create_field and delete_field without needing to name them, though no sibling is explicitly referenced.

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 (updating an existing field) and the description gives procedural detail for select fields (send the full option list). But it never states when to use this versus alternatives like create_field, or what prerequisites exist.

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 this is a non-read-only, non-destructive, non-idempotent write, so the safety profile is carried. The description's one real contribution is the partial-update contract ('only the given fields change'), which matters for a PATCH-style call; it says nothing about atomicity, partial-batch failure, or the typecast default.

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: scope first, then the semantics of the write. Nothing redundant and nothing 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?

Adequate for a simple batch mutation, but for a non-atomic, non-idempotent write with 4 params and no output schema it leaves open what happens on partial failure and whether retries are safe. Those are the details an agent most needs before calling a batch updater.

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 50%, with 'table', 'typecast', and 'fields' well documented in-schema, but 'baseId' and the per-record 'id' undocumented anywhere. The description restates the '1 to 200' bound and 'by id' that the schema already encodes via minItems/maxItems/required, so it adds little new parameter meaning.

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 (update records), plus a scope bound ('1 to 200 records by id') that separates it from create_records and delete_records. It does not explicitly name a sibling, and its distinction from update_table/update_field is only implied by the word 'records'.

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?

No statement of when to use this versus create_records or update_field, no prerequisites (permissions, base/table access), and no guidance on batch sizing decisions. The reader must infer everything about tool selection from the name.

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 a non-destructive, non-idempotent, closed-world mutation, so the safety profile is covered. The description adds the notable side effect that the primary field itself can be changed, but says nothing about permission requirements, name-collision behavior, or downstream impact on views/relations that reference the 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 short sentence with the mutating operations front-loaded and no filler. Nothing in it is redundant.

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 four-parameter mutation with sparse schema documentation and no output schema, the description is too thin: it never identifies required inputs (baseId, table), failure modes, or what a successful update returns. The agent must open the schema to call this safely.

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 only 25%, so the description needs to carry more weight. It implies the 'name' and 'primaryField' parameters through the operations it lists, but says nothing about 'baseId' (undocumented anywhere) and leaves 'table' to the schema's brief note.

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 gives a specific verb and resource plus the two mutating operations it supports (rename, change primary field), which lets an agent distinguish it from create_table, delete_table, and update_field. It stops short of naming those siblings explicitly, so it isn't fully discriminating.

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 when-to-use guidance, no prerequisites (base/table must already exist), and no exclusions or routing to alternatives such as update_field or create_table. Usage is only inferable from the listed operations.

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 mutation (readOnlyHint=false), non-destructive, and non-idempotent, so the safety profile is covered. The description adds genuinely new behavioral information the annotations do not carry: merge-vs-clear semantics for omitted fields versus explicit null. It stops short of stating what is returned or what permissions are needed.

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 filler. The capability list comes first and the partial-update rule second, which is the right ordering for an agent that needs to know what it can change before how.

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 15-parameter mutation tool with no output schema, the description covers the two things that matter most: which fields are settable and how omitted/null values behave. Gaps remain around return value, permissions, and validation constraints (e.g. the maxItems limits on sort/filter), but the schema itself carries most of that.

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 only 47%, so the description has to compensate, and it does at the category level: it names the name/filter/sort/hiddenFields families and flags that further settings are view-type specific (which maps to groupBy, dateField, laneField, coverField, timelineScale). The 'null clears one' sentence is the key semantic that the anyOf-null schemas do not spell out; only calendarMode and timelineScale remain unexplained in both places.

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?

Uses specific verbs (rename, change) against a specific resource (view) and enumerates the mutable facets: filter, sort, hidden fields, type-specific settings. An agent can distinguish it from create_view or update_table without opening the schema, 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?

The wording implies this operates on an existing view (as opposed to create_view), and the 'settings you leave out are kept' clause implicitly scopes it to partial edits. However, there is no explicit when-to-use/when-not statement, no mention of alternatives, and no prerequisite guidance such as required permissions or which view types accept which settings.

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