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

Annotations already declare readOnly=true, idempotent=true, and destructive=false, providing safety transparency. The description adds that the tool detects schema changes, which is useful context but not deep behavioral detail (e.g., whether it hits live APIs or what happens on network failure). With annotations covering the safety profile, this is an acceptable level of additional transparency.

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 that immediately states the core function. Every clause adds value: what it compares, between which environments, and what kinds of differences it detects. There is no filler or repetition.

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

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

For a no-param, no-output-schema tool, the description is adequately complete. It explains the input (implicitly none), the action, and the kind of information that will be produced (detected changes). It could mention the return format or what happens if environments are unreachable, but these are not critical gaps given the tool's simplicity.

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 has zero parameters, so the schema is trivially fully covered. Per the baseline for 0 params, this dimension gets a 4. The description adds meaning by explaining the comparison action, but there are no params to clarify anyway.

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

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

The description clearly states a specific verb ('Compares') and a specific resource ('schema between development and live Bubble environments'). It differentiates from siblings like bubble_get_schema and bubble_export_schema by emphasizing the comparison/detection of changes. The listed detected changes (new types, removed types, etc.) make the tool's purpose unmistakable.

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 the tool (when you need to know differences between environments) but does not explicitly state scenarios or exclude alternatives. It doesn't mention when to prefer this over bubble_get_schema or bubble_schema_summary. The guidance is present through listing the detection focus, but there are no explicit 'use this when' conditions.

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, idempotentHint=true, and destructiveHint=false, so the agent knows this is a safe read operation. The description adds behavioral context by specifying the output format (TDD-format markdown) and the contents (entity summary table and field specifications), which goes beyond what annotations convey.

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

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

The description is a single, well-structured sentence that front-loads the action ('Exports the Bubble.io schema as TDD-format markdown') and then adds useful detail about the contents. Every word earns its place, with no filler or redundancy.

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

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

With no parameters and no output schema, the description carries the full burden of explaining the tool's behavior. It clearly states the output format and what the markdown includes, which is sufficient for the agent to understand the tool's purpose and expected result. No missing critical information.

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 has zero parameters, and the schema coverage is 100% (empty schema). Since there are no parameter to document, the baseline for parameter semantics is 4, and the description does not need to add parameter details. It correctly focuses on the output.

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

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

The description clearly states the tool exports the Bubble.io schema as TDD-format markdown, and specifies the contents (entity summary table and detailed field specifications). This distinguishes it from sibling tools like bubble_get_schema or bubble_schema_summary, which likely provide schema data in other formats.

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 use when a TDD-format markdown export of the schema is needed, but it does not explicitly compare with alternatives or state when not to use it. Sibling tools like bubble_get_schema might be simpler alternatives, but no such guidance is provided.

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, and non-destructive behavior, lowering the bar. The description adds valuable context by stating it samples records, calculates rates, and uses a specific 5% threshold for dead fields. It does not discuss performance or sampling methodology, but for a read-only analysis tool, this is sufficient transparency.

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

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

Two compact sentences front-load the action and key result. Every word earns its place, with no fluff or repetition of schema fields. The threshold detail is useful and efficiently stated.

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

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

For a tool with two parameters and no output schema, the description covers the purpose, method (sampling), and a specific output characteristic (dead fields with <5% population). It omits what the exact return format looks like, but given the simplicity and read-only nature, it is nearly complete. Could mention if it returns per-field percentages, but not essential.

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

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

Schema coverage is 100% with both dataType and sample_size already described in the schema. The description adds no new parameter details beyond what the schema provides, so the baseline of 3 applies. It does indirectly reference dataType as 'Bubble data type' but does not enhance the schema's clarity.

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

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

The description clearly states the tool's purpose: sampling records, calculating field population rates, and identifying dead fields. This specific verb+resource combination distinguishes it from siblings like bubble_schema_summary or bubble_find_orphans, which focus on schema structure or orphan records rather than field usage.

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 this tool: when you need to assess field population and find dead fields. It does not explicitly mention alternatives or exclusions, but the context is clear and distinct from sibling tools, so it provides adequate guidance without needing to name alternatives.

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 already disclose read-only, idempotent, and non-destructive behavior. The description adds context about sampling records and checking reference fields, which goes beyond the schema and annotations by explaining the tool's operational approach. However, it does not describe the return format or pagination.

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 sentences, front-loaded with the core purpose, and every word adds value. No filler or redundancy.

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

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

The description explains the core functionality and samples behavior, which is adequate for a read-only scan tool. However, since there is no output schema, the description should have clarified what the tool returns (e.g., list of orphaned references, counts, or summary) and any limitations of sampling. This gap prevents a higher score.

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

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

Schema coverage is 100%, and both parameters have descriptions in the schema. The tool description itself does not add additional parameter detail beyond what's already provided, so it meets the baseline of 3 without needing to compensate.

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 ('Scans records for broken references') and clearly identifies the resource (records with foreign keys). It distinguishes itself from siblings by focusing on orphaned foreign keys, which is unique among the listed 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 provides clear context about when to use the tool (to detect broken references in records) but does not explicitly mention alternatives or exclusions. It implies a diagnostic/validation use case, which is enough for an agent to infer appropriate usage.

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, idempotentHint=true, and destructiveHint=false, which fully cover the safety profile. The description adds no additional behavioral context such as what happens if the ID does not exist, authentication needs, or response format. Since annotations are comprehensive, the lack of extra context keeps this at a 3.

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, clear sentence that is front-loaded with the action and object, with zero filler words. It perfectly matches the simplicity of a get-by-ID operation.

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 2-parameter, read-only tool with rich annotations and no output schema, the description covers the essential purpose and required inputs. It does not mention edge-case behavior (e.g., missing ID handling), but that is a minor gap given the simplicity and the annotations.

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% — both `id` and `dataType` have descriptive definitions. The description only restates these in prose ('data type and unique ID') without adding new semantic detail, so it does not go beyond the schema baseline.

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

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

The description uses a specific verb 'Retrieve' and clearly identifies the resource as a 'single Bubble.io data object' located by 'data type and unique ID'. This distinguishes it from sibling tools like bubble_search and bubble_search_all, which are search operations.

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 phrase 'by its data type and unique ID' — the agent knows it needs those two inputs. However, the description does not explicitly state when to use this over alternative tools (e.g., bubble_search for queries), nor does it mention any exclusions or prerequisites.

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 read-only, idempotent, and non-destructive behavior. The description adds valuable context by stating 'The API token is never exposed,' which is a security guarantee beyond the annotations. It also clarifies the returned fields, enhancing transparency without contradicting 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 two sentences long, front-loaded with the primary purpose, and contains no redundant or tangential information. Every word adds value, including the security note.

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

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

Given the tool's simplicity (no parameters, no output schema), the description adequately reveals the return content (app URL, environment, mode, rate limit) and adds a security behavior. It is complete for a straightforward environment configuration getter.

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 has zero parameters, so the baseline is 4. The description does not need to add parameter details, but it does mention the output fields, which helps clarify what the tool returns despite having no inputs.

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 the specific verb 'Return' and clearly identifies the resource as 'current server environment configuration' with the fields app URL, environment, mode, and rate limit. It is distinct from siblings like bubble_health_check and bubble_compare_environments, though it does not explicitly name 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 description implies usage (use when you need environment configuration) but provides no explicit when-to-use or alternative comparisons. It does not mention exclusions or conditions, so guidance is only at an implied level.

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 provide readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds the source endpoint and output content, but does not disclose additional behavioral traits like pagination, performance, or error conditions. This adds some value beyond annotations but not a rich depth of context.

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

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

The description is a single, focused sentence that front-loads the action and resource. Every word adds value, with no redundancy or unrelated 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?

Given the tool's simplicity (no parameters, no output schema, and strong annotations), the description is complete. It explains the purpose, the endpoint, and the content of the response, which is all the agent needs for a read-only schema retrieval.

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 has zero parameters and schema coverage is 100%, so the description does not need to explain parameters. Per the rubric, zero-parameter tools receive a baseline of 4.

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

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

The description clearly states the verb 'Retrieve', the resource 'full Bubble.io app schema', the source '/meta endpoint', and what it lists ('all data types and their fields'). It distinguishes itself from sibling tools like bubble_export_schema and bubble_schema_summary by specifying the endpoint and the exhaustive nature of the retrieval.

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 through its purpose statement (retrieve the full schema), but it does not explicitly state when to use this tool versus alternatives, nor does it mention any exclusions or prerequisites. The context is clear but lacks explicit guidance.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the safety profile is known. The description adds that it returns a score (0-100), section breakdowns, and top recommendations, which is useful behavioral information about the output 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, well-structured sentence that front-loads the purpose and lists key outputs. Every clause adds value 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?

Given the tool has no parameters, no output schema, and strong annotations, the description covers the essential information: what it does and what it returns. It is complete for an agent to decide whether to call this 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?

The tool has zero parameters, and the schema reflects that. With no parameters, the description correctly omits parameter details; the baseline of 4 applies as the schema fully covers everything needed.

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

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

The description clearly states the tool performs a comprehensive health check combining privacy audit and dead field detection, and specifies the outputs (score, breakdowns, recommendations). It distinguishes from siblings by indicating it combines two specific functions, though it doesn't explicitly name 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 description implies this is the combined tool versus the individual privacy audit or dead field detection tools, but it doesn't give explicit guidance on when to use this instead of the specific sibling tools. It lacks clear exclusions or alternatives.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the read-only nature is established. The description adds useful behavioral context by stating it produces an 'ordered' plan with specific step types (add_field, create_type, remove_field), which goes beyond the annotations without contradicting them.

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

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

The description is two sentences with no filler. It front-loads the action and purpose, then lists the outputs. Every word 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?

The tool has a single parameter, no output schema, and strong annotations. The description explains the core function and the nature of the output (ordered plan with step types), which is sufficient for the tool's simplicity. No gaps in required context.

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

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

The input schema has 100% description coverage for tdd_path, so the schema already documents the parameter meaning. The description adds only a minor contextual hint ('target TDD file'), which is not enough to move beyond the baseline of 3.

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

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

The description uses a specific verb ('Generates') and resource ('ordered migration plan'), clearly distinguishes from sibling tools by focusing on comparing a TDD file to live schema, and lists concrete output types (add_field, create_type, remove_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 description provides clear context for when to use the tool: when comparing a target TDD file against the live Bubble.io schema to generate migration steps. It does not explicitly name alternatives or exclusions, but the context is specific enough for an agent to differentiate.

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, so the agent knows this is a safe read-only operation. The description adds the 'low cardinality' heuristic but does not disclose return format or potential performance implications, which is acceptable given 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 concise sentence with a front-loaded verb ('Scans') and no wasted words.

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

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

The description is complete for a read-only audit tool with no parameters, but it doesn't describe the output format or how the results are presented. Given no output schema, a bit more would be welcome, but the core purpose is fully covered.

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 has zero parameters, so the description does not need to explain parameter semantics. The baseline for 0 params is 4.

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

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

The description clearly states the tool scans text fields across all data types and identifies low-cardinality fields for option-set conversion. This specific verb+resource distinguishes it from sibling audit tools like bubble_suggest_indexes or bubble_field_usage.

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 the tool is used for auditing text fields to find option-set candidates based on low cardinality, but it does not explicitly discuss when to use it over alternatives or mention any exclusions. No direct comparison to sibling tools is provided.

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, idempotentHint=true, destructiveHint=false, so the safety profile is established. The description adds value by detailing what the audit covers (sensitive fields, PII exposure, API write access) and the output format (score + issues), which complements the annotations without contradiction.

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

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

Two sentences, front-loaded with the action and resource, no fluff. Every word contributes meaning: the risk categories and return format are concise yet informative.

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 parameters and no output schema, the description provides all necessary context: what the tool does, what it checks, and what it returns. Annotations cover safety, making this description complete for agent selection and invocation.

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

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

The tool takes 0 parameters, so there is nothing to explain. The baseline of 4 applies, and the description does not need to add parameter details.

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 ('Audits') with a clear resource ('Bubble.io schema') and defines the scope (privacy risks: sensitive fields, PII exposure, API write access). It also states the return value (score 0–100 and issues list), distinguishing it from sibling tools like bubble_get_schema or bubble_field_usage.

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 clearly implies when to use this tool: when a privacy audit of the schema is needed. It does not explicitly name alternatives or state when not to use it, but the context is clear enough for an agent to select it appropriately among 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=true, openWorldHint=true, and idempotentHint=true, establishing a safe read-only operation. The description adds behavioral detail about sampling and the specific checks performed (empty/null fields, fully empty records), which is valuable context beyond the annotation values.

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, efficient sentence that conveys the core purpose and method with no filler words. Every part contributes to understanding the 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?

The tool is simple (2 params, no output schema), but annotations provide safety context. The description covers the function adequately. However, it doesn't mention what the tool returns or how results are reported, which could be useful given the lack of an output schema.

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

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

Schema description coverage is 100%: both dataType and sample_size have meaningful descriptions. The tool description reinforces their semantic roles ('given data type', 'sampling') but doesn't add significant new meaning beyond what the schema already provides.

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 'validates' with a clear resource 'records of a given Bubble data type' and describes the method 'by sampling and checking for empty or null fields and fully empty records.' This distinguishes it from sibling tools like bubble_tdd_validate or bubble_health_check.

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

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

The description provides no explicit guidance on when to use this tool versus alternatives. It doesn't mention typical use cases, prerequisites, or mention sibling tools. The context is implied 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?

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, setting a safe baseline. The description adds context that it returns a summary rather than a raw schema, but does not disclose additional behavioral traits like potential performance implications or rate limits.

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

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

The description is a single, well-structured sentence that front-loads the action ('Fetches') and clearly communicates the output. There is no redundant 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?

Given the tool's simplicity (no parameters, no output schema), the description adequately covers the return value ('human-readable summary' with specific contents) and the operation. The annotations cover safety, making the description complete for this context.

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 has zero parameters, so the baseline is 4 per the rubric. The description adds no parameter information, but none is needed.

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

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

The description clearly states the tool fetches the Bubble.io schema and returns a human-readable summary, specifying the exact content (types, field counts, relationships). This distinguishes it from sibling tools like bubble_get_schema, which likely returns raw schema data.

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

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

The usage context is implied by the function: it is for obtaining a summarized overview of the schema. However, there is no explicit guidance on when to use this versus alternatives such as bubble_get_schema, nor any exclusionary criteria.

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 readOnly, idempotent, and non-destructive behavior. The description adds minor behavioral context (optional constraints, sorting, pagination) but does not disclose additional traits like return format or cursor semantics. With annotations present, this is adequate but not enriched beyond structured 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 a single, concise sentence that front-loads the core purpose and optional features. There is no wasted text or redundancy.

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

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

With a well-documented schema and safety annotations, the description is largely complete. It does not explain the return value (e.g., list of objects, count), but for a simple search tool this is a minor gap, especially given no output schema exists.

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 fully documents all parameters. The description's mention of constraints, sorting, and pagination aligns with the schema but adds no extra meaning beyond what is already provided.

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

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

The description clearly states the action (search), the resource (Bubble.io data objects of a given type), and the key capabilities (optional constraints, sorting, pagination). It distinguishes itself from siblings like bubble_get (single object) and bubble_search_all (all types) by specifying 'of a given type'.

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 for a specific data type but does not explicitly state when to use this tool vs alternatives. It lacks explicit when-to-use/when-not-to-use guidance or alternative recommendations, though the scoping to a given type is a clear contextual clue.

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

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

Annotations already mark it as read-only, idempotent, and non-destructive. The description adds valuable behavior: auto-pagination, combined results, and a capped flag when the limit is reached. This goes beyond annotations but doesn't fully cover edge cases like error handling or empty results.

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 sentences, front-loaded with the primary action, and then reports the return behavior. Every word contributes meaning, with no fluff or repetition of schema details.

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

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

Given the tool's moderate complexity and no output schema, the description adequately covers the core pagination behavior and the capped flag. It doesn't explain how constraints/sort affect pagination, but these are documented in the input schema. Overall, it provides sufficient context for correct use.

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

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

Schema coverage is 100%, so the parameters are fully documented in the schema. The description only loosely references 'configurable max' without adding syntax details, which the schema already provides. Thus it meets the baseline without further enrichment.

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 ('auto-paginates'), the resource ('all records of a Bubble data type'), and a key constraint ('up to a configurable max'). This clearly distinguishes it from sibling tools like bubble_search and bubble_get, which likely operate on single pages or 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?

The description clearly indicates this tool is for retrieving all records of a data type, implying use when a full sweep is needed. However, it does not explicitly state when to avoid this tool or mention alternatives such as bubble_search for manual pagination, so it falls short of a 5.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is clear. The description adds context about the inputs it analyzes (schema and record counts), but does not disclose additional behavioral traits such as whether it makes external calls or how recommendations are generated. This meets the lower bar set by comprehensive 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?

A single, well-structured sentence that conveys purpose, input, and output without redundancy. Every word earns its place, and the information is front-loaded.

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

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

Given the tool's simplicity (no params, no output schema), the description provides adequate context by stating the analysis targets and the nature of the output. It could be slightly more explicit about the return format, but the core purpose is fully communicated. Annotations handle safety concerns, so fewer caveats are needed.

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 has zero parameters, so the schema provides no parameter semantics. The description does not need to explain parameters, and the baseline for 0 params is 4. It clearly conveys what the tool does with its implicit inputs (schema and record counts), which is sufficient.

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

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

The description clearly states a specific verb ('Analyses') and resource ('Bubble.io schema and record counts'), with a defined outcome ('suggest fields that would benefit from database indexes'). This distinguishes it from sibling tools like bubble_get_schema or bubble_field_usage by focusing on index recommendations.

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 purpose implies usage when index suggestions are needed, but there is no explicit when/when-not guidance or mention of alternatives. It does not explain how this tool complements or differs from siblings, so the usage context is only implied.

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, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds that the tool returns endpoint, data type, and schema information, but does not provide details on response format, caching, or rate limits, which would be additional value beyond annotations.

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

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

The description is two sentences long and directly states the function, return value, and usage guidance. Every sentence contributes useful information with no redundancy or 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 simple (no parameters) and the description fully explains what it does and what it returns. Even without an output schema, the description provides enough context for an agent to understand the tool's purpose and result.

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 has zero parameters, and the description clearly explains the return value, which serves the baseline requirement for tools without parameters. No parameter-specific documentation is needed.

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 the specific verb 'Fetches' with the resource 'Swagger/OpenAPI spec' and clearly states what it returns: available API endpoints, data types, and schemas. It distinguishes itself from siblings like bubble_get_schema and bubble_export_schema by focusing on the OpenAPI specification.

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

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

The description provides clear usage context: 'Use this to understand what operations and fields are available before making API calls.' It does not explicitly mention alternatives or exclusions, but the intended use case is well communicated.

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, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds the reporting specifics but no additional behavioral context such as auth requirements, failure modes, or side effects. While not contradictory, it does not enrich transparency 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 that states the action, resource, and output categories without waste. Every clause contributes to understanding, making it highly concise and well-structured.

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 has one parameter, robust annotations, and the description explicitly enumerates the validation categories returned. Although there is no output schema, the report types are listed, making the behavior sufficiently clear for a simple validation tool. It omits the exact report format or exit codes, but this is a minor gap given the tool's simplicity.

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

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

The input schema fully documents the only parameter (tdd_path) with a description and 100% coverage. The tool description adds no further parameter semantics, but the high schema coverage justifies the baseline score of 3, as the structured data carries the 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?

The description uses the specific verb 'Validates' with a clear resource ('TDD markdown file against the live Bubble.io schema') and explicitly lists the report outputs ('missing types, missing fields, type mismatches, and extra fields'). This distinguishes it from sibling tools like bubble_get_schema or bubble_record_validator by focusing on validation against the live 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 context (validating a TDD file) but provides no explicit guidance on when to choose this tool over siblings, no exclusions, and no alternative references. It is adequate for an agent to infer the primary use case but lacks direct when-to-use or when-not-to-use information.

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 disclose read-only, idempotent, and non-destructive behavior, so the bar is lower. The description adds value by specifying the return content ('workflow names and parameters'), which is not evident from the annotations or schema, thus providing useful contextual 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?

The description is two sentences, front-loaded with the primary action, and every word contributes meaning. It is concise and well-structured with no superfluous 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?

Given the tool has no input parameters and no output schema, the description provides sufficient information: it lists all API workflows and returns their names and parameters. This covers the essential context needed for an agent to understand the tool's purpose and output.

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 has zero parameters, so the baseline is 4. The description does not need to explain parameter semantics, and the empty schema confirms no parameters. The mention of 'parameters' refers to workflow parameters, not tool parameters, which is clear from context.

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

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

The description clearly states the tool's purpose with a specific verb 'Lists' and a specific resource 'all API workflows defined in the Bubble.io app schema'. It distinguishes itself from sibling tools by focusing on workflows rather than the full schema or other aspects, making the purpose immediately clear.

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

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

The description implies when to use the tool (when you need a list of API workflows) but does not explicitly mention alternatives or exclusions. It lacks guidance on choosing this over related tools like bubble_get_schema or bubble_schema_summary, so the usage context is only implied.

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

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

Annotations already declare read-only, idempotent, and non-destructive behavior. The description adds valuable context beyond that by stating that search estimates scale by dataset size and that expensive patterns are flagged. It does not describe return format or exact output, but for a computed estimate tool, this is reasonable given the annotation coverage.

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 the primary purpose in the first sentence and a beneficial behavior in the second. Every word earns its place, with no redundancy or unnecessary detail.

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 only 3 parameters and no output schema, the description covers the core function well but omits what the estimate looks like (return format, units, etc.) and lacks explicit usage guidance. The scaling/flagging note adds some operational context, but the absence of output details and alternatives leaves modest completeness 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 100%: all three parameters (dataType, operation, constraints) have meaningful descriptions. The description itself does not add parameter-specific details beyond what the schema provides, so it remains at the baseline for full schema coverage.

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 starts with a specific verb 'Estimates' and clearly identifies the resource ('Workload Units (WU) for a Bubble.io operation'). The additional detail about scaling and flagging expensive patterns further distinguishes this tool from all siblings, none of which estimate WU, making the purpose unambiguous.

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

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

Usage is implied: this is the tool for estimating WU for a Bubble.io operation. However, there is no explicit statement of when to use it versus alternatives, nor any exclusion criteria. The mention of scaling by dataset size and flagging expensive patterns gives context but does not directly guide tool selection.

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