floot

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

Annotations only say readOnlyHint=false, openWorldHint=false, destructiveHint=false; the description carries the real behavioral burden and does so richly: rejection with supported-alternative naming, version pinning/substitution, installation on the project VM, persistence of resolved versions, and the slow-then-fast two-call persistence pattern. No contradiction with annotations — mutation (readOnly=false) matches 'Add npm packages', and nothing suggests destructiveness.

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

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

The description is dense (roughly a hundred words across five sentences), but every sentence earns its place given the 0% schema coverage: purpose, exclusions, version pinning, install target, and the two-call pattern. It is front-loaded with the core purpose. It sits at the upper edge of appropriate length, with the kysely detail being specific but justifiably high-value.

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

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

For a two-parameter mutating tool with no output schema, the description covers validation, rejection behavior, exclusion rules, version pinning, install location, persistence, and the async job-then-recall flow. Minor gaps remain: it does not explain what the response/return looks like, how to correlate with job status, or the rationale for the second call beyond persistence, 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 description coverage is 0%, so the description must compensate — and it largely does. The `packages` parameter semantics are substantially enriched: bare names install pinned versions, explicit name@version overrides are for deliberate upgrades, and packages are validated against a supported set. `projectId` is only implied as the target project/VM ('Installs on the project VM'), leaving its meaning to inference rather than explicit statement.

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

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

The description opens with a specific verb and resource: 'Add npm packages to the project', and immediately adds scope ('validated against Floot's supported set'). It is clearly distinguishable from the sibling remove_dependency and from file-edit tools, and the 'add_dependency again' self-reference reinforces its exact role. No tautology or vagueness.

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?

Strong when/when-not guidance is present: avoid node-gyp/native packages, WASM modules, and large-binary bundles, with explicit exceptions and a version-nuance example for kysely. It also gives an invocation pattern for the async two-call flow. However, it never names alternatives (e.g., remove_dependency for removal, or the job-status tool for monitoring the slow install), so the 'vs alternatives' part is implicit rather than explicit.

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

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

The description goes far beyond the sparse annotations (readOnlyHint=false, openWorldHint=false, destructiveHint=false) by disclosing atomicity, the exact patch format, the destructive nature of Delete (item-scoped, removes siblings), the overwriting behavior of Add, the absence of Move support, and the failure mode when a patch is cut off (entire patch rejected). It also provides the modesty constraint. This richly explains behavior beyond what the annotations indicate.

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

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

The description is long but dense and logically structured: purpose first, then the format specification, followed by critical usage warnings and size guidance. Every sentence contributes useful information, and the front-loading makes the core purpose clear immediately. The length is justified by the complexity of the tool (multiple operations, atomic semantics, subtle pitfalls), though a brief example or more compact phrasing might improve scannability.

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 complexity of the tool (complex patch format, atomic multi-file operations, destructive behavior, path scheme), the description covers most essential aspects: the envelope format, operation types, path resolution, destructive warnings, rename workaround, and size constraints. It stops short of explaining the expected_version parameter and does not detail success/failure responses beyond the 'missing *** End Patch' rejection. It also omits any mention of rollback or atomicity enforcement outcome. For a tool of this complexity, these gaps are notable but not critical, so a 4 seems appropriate.

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

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

The schema has 0% description coverage for all three parameters: patch, projectId, expected_version. The description provides a thorough explanation of the patch string format, including envelope markers and line conventions, which is highly valuable. However, it does not explain projectId (though its meaning is likely clear from context) nor expected_version (which appears to be a version-check parameter but is never mentioned). With a zero-coverage schema, the description should compensate for all parameters, and it falls short for two of the three.

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 immediately states the action ('apply a V4A patch'), the resource ('a Floot project'), and the capability ('create, update, and delete multiple files in ONE atomic operation'). It also names the patch format and lists the exact operations, which clearly distinguishes it from sibling tools like edit_file, delete_file, or write_file, which handle single files or different 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?

The description provides explicit guidance on when to use specific operations within the patch (e.g., Add File for wholesale replacement, Delete for item-scoped removal), and warns against combining Delete+Add unnecessarily. It also explains the unsupported 'Move to' operation and how to rename instead, and advises splitting large changes. However, it does not explicitly contrast apply_patch with single-file tools like edit_file or write_file, so the selection criterion for when to prefer this multi-file tool over those 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 provide only readOnlyHint=false and destructiveHint=false, so the description adds the meaningful behavioral constraint that only pending requests are cancelable and that you can only cancel requests you created. It does not describe side effects (e.g., state changes or response), but the core behavioral limits are disclosed.

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 efficiently worded sentences. The primary purpose is front-loaded, followed by the constraint and usage trigger. No redundant phrases or unnecessary details are present.

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

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

For a simple two-parameter cancel operation, the description covers the what, when, and the pending/complete distinction. However, it omits how the agent obtains the required identifiers for the non-screenshot request types (no mention of returned fields), and it does not define projectId. Given no output schema and 0% schema coverage, these gaps make calling the tool correctly less certain.

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

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

Schema description coverage is 0%, so the description must compensate. While it mentions 'jobId from that tool' for screenshot_preview, it does not explicitly map jobId or projectId for the other request types, nor does it explain what projectId represents. The agent is left to infer that the identifiers come from the respective tools, which is underspecified for reliable invocation.

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 ('Withdraw') and resource ('a pending request you created'), and enumerates the three exact request types with their originating tools. This clearly distinguishes the tool's scope from all sibling tools, leaving no ambiguity about what it operates on.

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 explicit invocation context: 'Use when the user says to stop or they don't want to proceed.' It also sets a clear exclusion — 'Only pending requests can be cancelled — completed ones are final' — which prevents misuse on completed requests. The enumeration of source tools further guides when this is the appropriate tool.

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

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

Annotations provide readOnlyHint=false and destructiveHint=false, so the description does not need to repeat safety traits. The description adds the two-phase behavioral context (minting PUT URL, verifying landing, finishing request_user_upload) which is useful. However, it does not disclose side effects, permissions, or error behaviors beyond that. For a tool with these annotations, this is adequate but not rich.

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

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

The description is concise and front-loaded with the critical warning that it is not for agents, then explains both phases efficiently. Every sentence earns its place, though it could be structured slightly clearer by separating the exclusion from the functional description.

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 6 parameters, no output schema, and zero param descriptions, an agent would struggle to invoke this correctly without additional hints. The description does clarify the purpose and phases, but leaves parameter semantics and return behavior unexplained. Given its explicit exclusion from agent use, the incompleteness is partially mitigated, but as a tool definition it is not fully complete for an agent that might still attempt it.

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

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

Schema description coverage is 0%, so the description carries the full burden for parameter explanation. It mentions the 'picked file' and phases, but does not explain jobId, projectId, file_name, size_bytes, or content_type. The phase parameter is described indirectly ('presign'/'complete' roles) but not the others. The description fails to compensate for the lack of schema descriptions.

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

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

The description clearly states that this is an internal bridge for the upload card and explicitly warns it is not for agents, directing them to request_user_upload / upload_asset. It also details the two phases ('presign' and 'complete') with specific actions, making its function unambiguous and distinguishing it 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?

The description explicitly states when not to use this tool ('not for agents') and names the alternatives (request_user_upload / upload_asset). It also explains the two-phase usage flow, giving practical guidance on how the tool operates, which fully addresses when and when not to invoke it.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=false, so the description is not responsible for those basics. It adds valuable behavioral information: 'Importers of the source are left unchanged' clarifies a non-obvious side effect, and 'same type only' sets an important constraint. This goes beyond the annotations without contradicting them.

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

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

The description is two sentences with no wasted words. It front-loads the core purpose with an example, then covers constraints and batching efficiently. Every sentence earns its place.

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

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

For an operation that copies multiple items, the description covers the main behavioral details: naming rules, type constraints, side effects on importers, and batch invocation. The schema handles parameter structure. There is no output schema, so return values need not be explained. Minor gaps like error handling or directory recursion are not critical for an agent to call this tool correctly.

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

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

Schema description coverage is 0%, so the description must compensate. It explains the semantics of 'from' and 'to' through the example and the naming rules, and clarifies that 'copies' is an array applied in one call. However, it omits any context for 'expected_version' and 'projectId', which are also required. The description adds some meaning but does not fully cover all parameters.

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

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

The description clearly states it copies items to new names, with a concrete example. It distinguishes itself from siblings like rename_file by explicitly noting that importers of the source are left unchanged, which is a key differentiating behavior. It also adds constraints ('same type only', 'without extensions') that define scope precisely.

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: 'Importers of the source are left unchanged' implies that rename_file would be the alternative if importers should be updated, and 'Pass several copies to apply them in one call' gives batching guidance. However, it does not explicitly name an alternative tool or state when not to use it, leaving a small gap.

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 convey readOnlyHint=false and destructiveHint=false, but the description adds substantial behavioral context: it groups file/dependency changes, no-ops when nothing changed, and clarifies the restore scope (code/config only, not DB/assets/deployments). This goes well beyond the annotations' minimal mutation hints.

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

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

The description is front-loaded with the primary purpose and key constraints, then expands on timing, no-op behavior, and restore scope. Every sentence adds valuable information without redundancy. It is appropriately sized for a tool with 3 parameters and no output 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?

The description covers what the tool does, when to use it, parameter semantics, behavioral edge cases (no-op, restore scope), and even provides a title example. No output schema exists, so explaining the return value is not required. There is no missing information an agent would need to call it correctly.

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

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

Schema coverage is 0%, but the description compensates by explaining the title parameter ('short user-meaningful title describing what was accomplished') and description (optional detail). The required projectId is only implied through 'the project's Checkpoints panel,' not explicitly defined. Given that two of three params are meaningfully described and projectId is self-evident, this is a solid score.

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 ('Create') and resource ('a NAMED checkpoint — a labeled restore point'), and clearly distinguishes it from sibling file-operation tools by framing it as a checkpoint for grouping changes. It also specifies the user-facing panel, leaving no ambiguity about what the tool does.

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 instructs when to call: 'AFTER completing a coherent unit of work (a feature, a fix, a requested change set) — not after every file write.' It also gives a no-op condition and implies that other tools handle the actual file changes. This is strong usage guidance with a clear positive and negative directive.

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

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

Beyond the annotations (readOnlyHint=false, destructiveHint=false), the description reveals key behaviors: the project starts EMPTY, the result renders a live preview card, includes a first-build playbook, and initial_prompt is preserved and served back as <project-instructions>. It also warns not to paraphrase initial_prompt. These are meaningful operational details that an agent needs to know, and none contradict the annotations.

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

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

Three sentences carry a lot: purpose, a critical parameter requirement, and post-creation workflow. The core purpose is front-loaded, and each subsequent sentence adds necessary context. No filler or redundancy. Slightly dense but appropriate for the complexity.

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 return value (id), side effects (live preview card, empty project), and follow-up actions. It also clarifies the role of initial_prompt in the broader system. An agent has everything needed to invoke it correctly and know what to expect. No output schema means the description must explain the result, which it does.

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 50% schema coverage, the description adds substantial meaning for initial_prompt: it explains it must be the USER'S ORIGINAL REQUEST verbatim, that it grounds the project and is served back in list_files, and instructs not to paraphrase it. This goes well beyond the schema description. For the 'name' parameter, the description does not add anything, but the schema does not document it either; however, a project name is self-explanatory. The description compensates for the schema gap on the critical parameter.

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

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

The description opens with a clear verb and resource: 'Create a new Floot project... and return its id.' It also specifies the pre-seeded component library, distinguishing it from any other creation tools like create_checkpoint. The purpose is immediately understandable and unique among the 45 siblings.

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

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

The description gives explicit post-creation workflow guidance: 'a session normally continues straight into get_guides("design") and the first page rather than ending at the card.' This tells the agent when the tool is appropriate (starting a new project) and what to do next. However, it does not explicitly state when NOT to use it or mention alternatives, though none exist among siblings for project creation, so the guidance is sufficient.

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 destructiveHint=true, so the agent knows it's destructive. The description adds valuable behavioral detail beyond that: it explains cascading effects (deleting main code file removes css/tests; aux file only clears that part). This is significant context that annotations don't cover. It does not mention permissions or reversibility, but given destructiveHint is explicit, this is adequate. No contradiction found.

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 clear sentences with no filler. The critical nuance (cascading deletion) is front-loaded after the main verb. Every sentence adds value; no redundancy or irrelevant 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?

For a destructive delete tool, the description covers the key side effects (cascading behavior) that an agent must know to avoid accidental harm. It does not explain return values or error conditions, but since there is no output schema and the tool is destructive, the pragmatic aspects are well covered. The main gap is parameter semantics (especially expected_version), but overall it's sufficient for safe invocation.

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

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

Schema has 0% description coverage, meaning the description must compensate for parameters. The description mentions 'project file' and distinguishes between main and aux files, which maps partially to the 'path' parameter. However, it does not explain 'expected_version' (likely for optimistic concurrency) or 'projectId' purpose, which are not obvious. Since parameters are few (3) and two are required, the baseline is 3; description provides some but not full 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 description clearly states the tool deletes a project file and specifies a verb-resource pair, distinguishing it from siblings like copy_file, rename_file, and edit_file. It also covers a key aspect: deleting an item's main code file removes the whole item; this adds a specific behavioral nuance that differentiates it from generic deletion. However, it doesn't explicitly name alternative tools (e.g., 'to remove dependencies use remove_dependency'), so it's slightly below 5.

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

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

The description explains when the tool is appropriate: deleting files, and crucially, clarifies the consequences for main vs. aux files (removing whole item vs. part). This context is useful for deciding whether to delete a file versus editing it or using a different tool. However, it does not explicitly state when NOT to use it (e.g., when the file is a dependency, use remove_dependency) or list alternatives, so it's not 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?

It discloses the two most operationally important behaviors: old_string must match current content exactly (including whitespace) and must be unique unless replace_all is set. But it is silent on the expected_version parameter's conflict-locking behavior and on failure modes (e.g., what happens when old_string is not found or is non-unique without replace_all). With only readOnlyHint/destructiveHint annotations carrying no safety meaning, the description bears the burden and covers the core but not the conflict semantics.

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 with no filler; the core purpose is front-loaded, the matching constraint follows, and the sibling routing closes it. Every sentence earns its place, though the version/conflict behavior gap means it is not maximally packed.

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 8 parameters, 0% schema coverage, and no output schema, the description covers the editing semantics well but leaves meaningful gaps: expected_version behavior, failure/error behavior, and the duplicated str/string parameter ambiguity are all unexplained. An agent could call it correctly for the happy path but would not know how it handles version mismatches or non-unique matches.

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

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

Schema description coverage is 0%, so the description must compensate. It explains old_string, new_string, and replace_all meaningfully. However, it omits expected_version (a version-locking guard that likely carries conflict semantics) and projectId/path, and it does not resolve the schema's confusing duplication of old_str/new_str versus old_string/new_string — a real hazard for an agent choosing parameters.

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

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

The description names a specific verb ('Replace... with...') and a precise resource ('a project file'), and it explicitly distinguishes itself from the sibling write_file by instructing agents to prefer it for changes to existing files. This gives an agent enough to separate it from write_file without opening the schema.

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

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

It gives explicit guidance — 'Prefer this over write_file for changes to existing files' — which routes the agent correctly for the modification case. However, it does not mention apply_patch, another sibling capable of file modification, nor state the when-not-to case (new files) explicitly, though that is cleanly 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 declare destructiveHint=true and readOnlyHint=false, and the description aligns and enriches these by detailing the user-approval step, the automatic schema-helper re-pull, transaction default behavior, and timeout. It also explains which statements require no_transaction. No contradiction—the description extends the annotation-driven behavioral model substantially.

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

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

The description is longer but every sentence adds value: purpose, approval, schema re-pull, database condition, transaction, timeout. It is front-loaded with the core purpose and flows logically through invocation details. 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?

Covers the essential context: what the tool does, when to use it, parameters, transaction behavior, timeout, and the schema re-pull effect. It does not specify the return format for non-schema statements (e.g., affected rows or result set), and error handling is absent. Given the existence of a sibling query_database and the write intent, these gaps are minor but still leave some ambiguity for an agent.

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 must compensate. It explains `no_transaction` (required for VACUUM, INDEX CONCURRENTLY) and `database` (only when multiple databases exist), and implies `query` is the SQL statement. `projectId` is not explicitly described but is conventional and the overall semantics are clear enough. A strong but not perfect compensation for low schema 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 opens with 'Run a WRITE SQL statement against the project's Postgres database' and lists specific operations (CREATE/ALTER TABLE, INSERT, UPDATE, DELETE, DROP, migrations). This clearly distinguishes it from the read-only sibling query_database and the schema-only pull_database_schema, which is also referenced 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?

Provides explicit when-to-use guidance: approval flow for destructive statements, auto schema re-pull removing the need for a separate pull_database_schema call, the condition for passing `database`, and when to set `no_transaction`. It also notes the 90-second timeout. These instructions leave no ambiguity about invocation context.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds the id format behavior, but does not disclose what the response contains, error behaviors, or any limits. Given the simplicity and read-only nature, this is adequate but not rich.

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 zero waste. The primary purpose and formats are front-loaded, and the alternative tool is mentioned in a second sentence. Every word serves a clear function.

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 a single parameter and no output schema, the description is fairly complete. It clarifies the id format and points to alternatives for direct access. It does not describe the return value, but given it's a fetch of a search result, the agent likely has prior context from the search tool. A minor gap is the lack of explicit mention that this id originates from the search 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 description coverage is 0%, so the description must compensate. It thoroughly explains the 'id' parameter by defining two valid formats with placeholders, which is essential for correct usage. This adds significant meaning beyond the schema's bare 'string' type.

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 a search result by id, and explicitly defines the two id formats: a project overview ('<projectId>') or a file ('<projectId>:<path>'). It distinguishes itself from siblings by noting that read_file/list_files provide more detail for direct access, making the 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 gives clear context for when to use this tool vs. alternatives by stating 'For direct access to a known file or project, read_file/list_files give more detail.' This implies fetch is meant for search result ids, not known paths. While it doesn't enumerate other alternatives, the primary distinction is covered.

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 are empty/neutral (readOnlyHint=false, destructiveHint=false), so the description carries the behavioral burden. It discloses that images are written to project asset storage, registered in the asset manifest, and that returned paths only resolve on the app's own domain — key behavioral context beyond the schema. It could add error/limit behavior (e.g., maxItems=4), but the core side effects are disclosed with no contradiction.

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

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

Purpose is front-loaded in the first sentence, followed by behavioral detail and then usage alternatives. It is a long single block but every sentence carries information — no filler. Slightly denser than necessary, but the density is justified by the routing guidance.

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 nested-array complexity with no output schema, the description covers return format (project-relative /_cdn/static/ paths, domain-scoped), usage alternatives, timing, and the metadata sibling (update_project_metadata iconUrl). The only minor gap is the size enum, which is recoverable from the schema itself. Comprehensive for correct invocation.

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

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

Schema description coverage is 0%, so the description must compensate, but it does so only partially. It implies what 'name' and 'prompt' mean and explains what is returned, but it does not describe the 'size' enum values (square, landscape, etc.) or the 'description' field. It adds meaningful context about the output paths but leaves the per-item size/description semantics to the agent's inference.

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 ('Generate AI image assets directly into the project') with a clear resource and scope. It distinguishes itself from siblings by defining what counts as project-specific imagery versus stock (Unsplash) or pre-existing local files (upload_asset). An agent can confidently tell this apart from upload_asset without opening schemas.

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

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

Explicitly routes the agent: use for PROJECT-SPECIFIC imagery, use Unsplash URLs for generic stock, use upload_asset when a local file already exists. It also gives sequencing guidance ('Generate BEFORE building the components that use the images'). This is fully actionable when/when-not/alternatives 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 declare readOnlyHint=true and destructiveHint=false, and the description aligns with those. It adds substantial behavior beyond annotations: 'Cheap and text-only,' the reverting-detection warning ('re-read before editing if so'), and the multi-window selection semantics. It also instructs to call view_annotation for pending annotations. No contradiction with annotations.

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

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

The description is long (~150 words) but every sentence carries weight: it covers when to call, what it returns, edge cases (multi-window, revert), and follow-up actions. The most critical guidance (call FIRST, cheap) is front-loaded. It is not padded, though it could be tightened slightly without losing value.

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

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

For a tool that aggregates rich context from multiple windows and states, the description leaves nothing missing. It explains the output semantics (what the result says), the merging behavior, the revert caution, and the annotation follow-up. Even without an output schema, the agent knows what to expect and how to act. Fully complete for its 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?

The only parameter is projectId, with 0% schema description coverage. The description does not explain projectId at all, relying on it being an obvious identifier. While not misleading, it adds no meaning beyond the schema. Given low coverage, some compensation would be ideal, but the parameter is trivially understood, so a '3' reflects acceptable but not strong semantic support.

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 ('get') and resource ('current editor context'), then enumerates the concrete contents: active page/component, selection mapped to file:line, preview device, annotations, revert status, and queued requests. This goes well beyond a vague summary and clearly distinguishes it from siblings like view_annotation, which is referenced as a follow-up for annotations.

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

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

Gives explicit when-to-call guidance: 'Call this FIRST when the user refers to something without naming it... reports a problem without saying where... or implies they triggered something in Floot.' Provides concrete examples ('this', 'here', 'the button', 'it's broken', 'I clicked fix'). Also explains the multi-window selection merging behavior, directing the agent on how to interpret a 'no selection' from the answering window versus a deposited selection from another.

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 provide some context (idempotentHint=true, destructiveHint=false, readOnlyHint=false) but the description adds little: it only says 'identical tool,' which is a relational trait rather than actual behavioral information. It doesn't disclose what the tool does, side effects, or return behavior. With annotations present, the bar is lower, but the description doesn't add meaningful behavior beyond the alias statement.

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, no fluff, and the key alias information is front-loaded. It is appropriately sized for a redirect stub, and the structure immediately tells the agent to use the canonical 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 description is intentionally incomplete but directs the agent to get_guides for full usage, which is a valid strategy given the sibling exists. However, on its own it doesn't provide enough to invoke correctly (no parameter semantics or return expectations). It partially compensates by naming the authoritative source, but it's not self-contained.

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 description mentions no parameters. The three parameters (topic, topics, projectId) have no explanation anywhere. The description provides zero compensation, leaving the agent with no idea how to fill or interpret these 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 identifies the tool as a 'compatibility alias' of get_guides, which states its nature but not its function. It doesn't say what the tool actually does (e.g., retrieves guides by topic) and relies entirely on the reader knowing get_guides. This is more informative than a pure tautology but still vague about the core operation.

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 instructs to 'Prefer get_guides' and directs the agent to 'see it for full usage.' This is clear, decisive guidance on when and when-not to use this tool, naming the preferred sibling and the condition for using this alias. No ambiguity.

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?

Goes beyond the annotations by disclosing the side effect of auto-injecting seed code, stating it is idempotent and never overwrites existing files. This is exactly the kind of behavioral context an agent needs beyond the idempotentHint and readOnlyHint flags, and it aligns with annotations (readOnlyHint=false).

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 dense paragraph but well-organized: it starts with the core function, then details parameter usage, and ends with important side-effect caveats. No wasted words, though slightly long; the key points are 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?

Covers parameter usage and side effects thoroughly, but lacks a clear distinction from the similarly named sibling get_guide, and does not mention the response format of the guide list or any error/edge cases. Given the absence of an output schema, the description should at least hint at what the returned guides look 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 coverage is 0%, so the description must compensate. It explains all three parameters: topic (single guide id), topics (array of ids for multiple), and projectId (for injection context). Provides examples and clarifies the relationship between topic and topics. This fully makes up for the bare 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?

States a clear purpose: 'Floot documentation for agents' with explicit call patterns (no args, topic, topics). Provides a concrete example (topic:'floot-overview'). However, it does not differentiate from the sibling get_guide (singular), so it falls short of a 5.

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

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

Provides some context (read floot-overview before first code change, pass projectId when working on a project) but never explicitly says when to use this tool over the alternative get_guide. No exclusions or conditional routing to the sibling 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?

Beyond the readOnlyHint annotation, the description discloses detailed behavior: each poll returns a terminal state or 'still running', failed calls return stored errors, jobId uniqueness, non-blocking concurrency, frozen history after terminal, and acceptance of legacy ids. This adds significant value beyond the structured annotations.

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

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

The description is ~100 words, front-loaded with the core purpose, and each sentence adds relevant detail. It is slightly dense with many clauses but remains efficient and well-structured, earning a 4 for conciseness rather than verbosity.

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

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

The description covers return behavior (terminal states, error messages) and usage context (concurrency, history, legacy ids), which is essential. However, it omits any explanation of the optional wait_seconds parameter, a gap that prevents full completeness for callers. Otherwise it's quite thorough.

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

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

The schema provides no descriptions for jobId or wait_seconds, and the description only explains jobId (as the identifier of the polled job). The optional wait_seconds parameter is completely unmentioned, leaving agents without guidance on how it affects polling. With 0% schema coverage, the description must compensate but only partially does.

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 precise verb ('Poll') and resource ('a pending tool call by its jobId'), and clarifies the operation's nature as polling for result. It distinguishes itself from sibling tools like cancel_request by focusing on status retrieval, not cancellation or other actions.

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

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

The description gives clear when-to-use guidance: poll pending calls and repeat until terminal. It also specifies when NOT to use it (new user request should trigger a fresh call, not re-poll). However, it does not explicitly name alternative tools, though siblings like get_publish_status exist; the guidance is still sufficient for routing.

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

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

Annotations already mark readOnly and non-destructive; the description adds substantial context: logs live ~1 hour, cover dev backend + live session only, empty if no editor open, includes background jobs, and describes the browser network line format. This far exceeds the annotation baseline and fully discloses the tool's scope and limitations.

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

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

The description is long but extremely dense, with the 'FIRST step' hook front-loaded. Each clause adds new information (retention, source details, prod alternative). It is not a single-sentence terse statement, but it avoids redundancy and earns its length.

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 4 parameters (1 required), 0% schema coverage, and no output schema, the description is remarkably complete. It covers parameter semantics for two complex params, describes return contents, explains cross-referencing via log_reference_id, notes empty response conditions, and provides the alternative for prod logs. Nothing critical is missing for an agent to call this correctly.

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

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

Schema description coverage is 0%, so the description must compensate. It thoroughly explains 'source' (server vs. browser), 'log_reference_id' (pass from previous listing), and implies projectId via 'reads the project's runtime logs.' However, it never explains the 'limit' parameter (what it bounds, default, etc.) and projectId is only implied, not explicitly tied to the parameter. Two of four parameters lack direct treatment.

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 ('Reads') and resource ('project's runtime logs') and differentiates two modes (server and browser) with distinct contents. It also distinguishes itself from CloudWatch and directs to run_code_in_vm for published logs, making it non-confusable with 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?

Explicitly says 'Your FIRST step when debugging any runtime problem' and 'Call this before theorizing from an error message alone.' It also lists the alternative for published logs (run_code_in_vm's _floot.getProdBackendLogs) and even references get_guides for details. This is textbook when-to-use vs. when-not-to-use guidance.

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

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

Beyond the readOnlyHint and destructiveHint annotations, the description discloses critical behavioral traits: the URL carries an access token, is view-only, works only if shared exactly as returned, live-updates as you edit, and includes a sandbox API base for headless testing. It also clarifies that Floot hosts the app and warns against external hosting. This is rich context that annotations alone do not provide.

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

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

The description is intentionally detailed but not overly verbose. It front-loads the core action and then addresses usage caveats, token behavior, live-update nature, and the sandbox API in a logical sequence. Slightly long but each sentence adds value without redundancy.

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

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

The tool has a single parameter, no output schema, and annotations that only cover read-only/destructive hints. The description fully covers all needed information: what the result includes (preview link, sandbox API base), how it behaves (live-updates, view-only), and important constraints (token in URL, not for production, not for external hosting). Nothing an agent needs to call it correctly is missing.

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

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

The schema only defines projectId as a string with zero description. The description compensates by implying the parameter must refer to an existing project ('on an EXISTING project') and warns against using it right after create_project, which indirectly clarifies the expected input. While it does not explicitly spell out 'projectId is the identifier of an existing project,' the context strongly implies it, adding meaningful guidance beyond the bare schema.

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

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

The description clearly states the tool's purpose: 'Show the user a live preview card and return the preview link.' It identifies the resource (preview card/link) and the action (show/return). It distinguishes itself from siblings by explicitly contrasting with create_project (duplicate) and publish_app (production), making the uniqueness 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?

Provides explicit when-to-use guidance: 'typically called EARLY, before the first change' on existing projects. It gives a strong when-not-to-use: 'Do NOT call it right after create_project' because it duplicates the card. Also points to an alternative: 'to go to production use publish_app.' This is exactly the level of guidance expected.

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 the description adds meaningful behavioral context: it explains each field's semantics (paid plan disables badge, displayFlootLogo shows/hides badge) and confirms it is a snapshot. This goes beyond the structured annotations to give the agent full understanding of the tool's 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 packed with info yet well-structured: it front-loads the core definition, then explains fields, then gives usage guidance. No wasted words; every sentence carries value.

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

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

With no output schema, the description fully covers the return fields and their meanings. It also provides usage context (who calls it, when) and mentions sibling behavior. An agent has everything needed to call it correctly and interpret results.

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 has only projectId (required string) with no schema description (0% coverage). The description implicitly ties the parameter to the project ('for a project') but does not explicitly elaborate on projectId's format or purpose. Despite the low schema coverage, the parameter is trivially inferable, so this is only a minor 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 clearly states it is a 'Read-only publish snapshot for a project' and enumerates the specific fields returned (published, paid, displayFlootLogo), making the tool's purpose unambiguous and distinguishing it from sibling publish/unpublish 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?

Explicitly states when to use the tool ('on load to render fresh state' and 'check it before publishing') and names sibling alternatives with error conditions (publish_app errors when already published; republish_app errors when not), providing concrete routing 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 destructiveHint=false, so the safety profile is covered. The description adds value by detailing the exact return contents (file tree, sizes, dependencies, version, metadata fields), which is more than the annotations alone provide. No contradictions.

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 primary action (list file tree) and then concisely lists additional returned data and usage pointers. It is dense but not bloated, with useful detail in a compact form.

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 one parameter and no output schema, the description covers what is returned in detail and even includes a usage note about the version for write tools. It clearly states the relationship with update_project_metadata. Minor missing point: no mention of error conditions or pagination, but these are not critical 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?

Schema coverage is 0%, so the description must explain the single parameter projectId. It implicitly does so by stating the tool lists a Floot project's tree and metadata, making it clear projectId identifies that project. While not explicit, the context is sufficient for the simple parameter.

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 'List' and the resource (a Floot project's virtual file tree), and enumerates the included data: file sizes, dependencies, current version, and detailed project metadata. It differentiates from siblings by explicitly naming update_project_metadata as the tool that changes these settings and notes that the version should be passed to write 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?

It provides explicit when-to-use guidance: 'This is where to look up those settings' and contrasts with update_project_metadata which changes them. It also instructs the user to pass the version to write tools as expected_version, giving a concrete usage pattern.

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 description doesn't need to repeat that. It adds valuable behavioral context: the list is ordered by last-updated, name_filter is case-insensitive and matches the stored name (not the user-facing name), and a no-match filter returns the whole list on small accounts. This goes beyond annotations and helps the agent predict edge cases.

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 concise sentences with no filler. It front-loads the core functionality (what it returns and ordering) and then details the filter behavior. Every sentence adds information, and the structure is efficient.

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

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

For a simple read-only list tool with no output schema, the description is fairly complete: it lists the returned fields, ordering, and filter semantics. It doesn't cover pagination or error behavior, but given the minimal parameter set (limit and name_filter) and read-only annotation, what's missing is not critical. It could note that limit defaults, but the schema covers 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?

With schema description coverage at 0%, the description must compensate for both parameters. It thoroughly explains name_filter semantics (case-insensitive substring, stored vs. user name, fallback behavior), which adds real value. However, it does not describe limit at all, though limit's min/max are in the schema. Since name_filter gets rich treatment but limit is left to schema defaults, the compensation is partial.

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

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

The description states a specific verb ('List'), a specific resource ('Floot projects'), and enumerates the returned fields (id, name, last-updated, app icon) and ordering (most recently updated first). This clearly distinguishes it from sibling list tools like list_files and list_resources, which target different resources.

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 contextual details (ordering, filter behavior) but does not explicitly state when to use this tool versus alternatives or mention any prerequisites. It's implied that this is for listing projects, but there is no direct guidance on when not to use it or which sibling to prefer.

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 declare readOnlyHint=true, so the read-only nature is known. The description adds useful behavior: the three categories with their usability, the case-insensitive substring filtering behavior of 'query', and a pointer to get_guides('resources') for details. This goes beyond the annotations by explaining what the list contains and how filtering works, 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 well-organized with a numbered list for the three resource categories, a clear 'Call it to...' sentence for usage timing, and a brief note about the query parameter. Every sentence contributes meaning; there is no redundancy or filler. The key purpose is front-loaded, and the 'Read-only. Details: get_guides('resources').' coda is a compact pointer. This is appropriately sized for the amount of information conveyed.

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 two parameters (one required), no output schema, and annotations covering the safety profile, the description is complete. It gives the purpose, usage timing, parameter semantics, and even a fallback for deeper details (get_guides). The absence of a detailed return format is acceptable because the tool's purpose is clear and the read-only annotation reassures the agent; an output schema is not present, so the description does not need to explain it, but it does enough to enable correct invocation.

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

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

Schema description coverage is 0%, so the description must carry the burden. It thoroughly explains the 'query' parameter ('case-insensitive substring over names, descriptions, types, and env var names') and its purpose. The 'projectId' parameter is not explicitly described, but the opening line ('a project's code') makes its role obvious. The description compensates well for the lack of schema detail.

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 'List' and the resource ('env vars a project's code can use and the resources behind them'), then enumerates three specific categories. It distinguishes itself from siblings like provision_resource and request_external_resource by explicitly saying to call it before provisioning or requesting any credential. This is a specific, unambiguous purpose.

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?

Explicit guidance is given: 'Call it to learn what env vars exist before writing backend code, and BEFORE provisioning or requesting any credential (the owner may already have the one you need).' This tells the agent when to use this tool and implicitly when not to (i.e., before provisioning/requesting). It also explains the query parameter's filtering use case. No alternative tools are named, but the timing and rationale are unambiguous.

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; the description reinforces this with 'Does not modify the project.' It adds valuable behavioral context: requirement for an open window, fail-fast behavior with guidance, and the per-targetType semantics (e.g., file naming conventions and the need for example files). This exceeds the annotation baseline and covers most behavioral aspects, though it does not detail edge-case failure modes for invalid paths or missing examples beyond the general 'fails fast' statement.

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 relatively long but highly information-dense; every sentence contributes to operational clarity. It is front-loaded with the primary purpose, then systematically explains each targetType. While not maximally concise, it avoids fluff and is 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?

Given the tool's three distinct modes, no output schema, and moderate schema coverage, the description is complete for an agent to call it correctly. It covers all required parameters, explains file naming conventions, prerequisites, failure behavior, and how it relates to screenshot_preview. Nothing essential 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 description coverage is only 50% (name and path have descriptions; projectId and targetType do not). The description compensates thoroughly: it explains targetType values, the exact format for name (matching list_files), the path format with query/hash, and the mapping from file names to routes. It also clarifies that name is used differently for component vs page-examples. This adds substantial meaning beyond the raw 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 ('navigate') and resource ('the user's OPEN Floot preview'), and clearly distinguishes three targetType modes (page, component, page-examples), making it easy to understand what the tool does and how it differs from alternatives. It also names the pairing with screenshot_preview, clarifying its role.

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

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

The description gives clear usage context: use it to show the user what was built, and pair with screenshot_preview to see the result. It notes the prerequisite that a Floot window must be open and that it fails fast with guidance. However, it does not explicitly state when NOT to use it or name alternative tools for similar navigation (though few exist in the sibling list), so it falls just short of exhaustive 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 are minimal (readOnlyHint=false, destructiveHint=false, openWorldHint=false). The description adds valuable behavioral context: 'fully server-side (Floot mints all secrets; no keys to paste)', 'seeds the working code', idempotency ('re-running returns the existing resource and skips seed files that already exist'), and auto-provisioning for auth. It does not contradict annotations. A score of 4 because it covers the key side effects but could be more explicit about file modifications.

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

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

The description is long (~200 words) but well-structured: main purpose first, then a bulleted list of resources, followed by exclusions and behavior notes. Each sentence carries essential information (idempotency, exclusions, beta-gating). It is not overly verbose relative to the complexity, though it could be tightened by trimming redundant phrases.

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 complexity (7 resource types, exclusions, idempotency), the description covers all key aspects: what each resource does, exclusions, idempotency, and beta-gating. It lacks an explicit return-value description, but the mention of 'returns the existing resource' gives a hint. Overall it is sufficiently complete for an agent to invoke it correctly.

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

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

Schema description coverage is 0%, so the description must compensate. It thoroughly explains each enum value of 'resource' with details on secrets injected, pages/endpoints seeded, and helper functions. For 'projectId', it is a standard identifier and not elaborated, but that is acceptable. The resource parameter semantics are far beyond the bare enum names, justifying a 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 opens with a specific verb+resource ('Provision a Floot-managed backend resource') and immediately clarifies scope ('for the project'). It lists the concrete resource types and distinguishes itself from siblings by naming request_external_resource and get_guides as alternatives. An agent can tell exactly what this tool does and what it does not.

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?

Explicit guidance is given for when to use this tool vs alternatives: 'SENDING email ... is NOT a resource' and 'For a user's OWN external key ... use request_external_resource instead.' It also clarifies that email is handled by get_guides("email"). This eliminates ambiguity and routes the agent correctly.

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 indicate this is not read-only and not destructive, so the mutation nature is covered. The description adds a pointer to get_guides for modes, inputs, and statuses, which suggests complexity but doesn't disclose specific side effects, permissions, or reversibility. It adds some context but not rich behavioral detail beyond what annotations imply.

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 purpose and usage trigger, followed by the alternative tool, and ends with a pointer to the guide. Every sentence serves a distinct function with no wasted words, achieving excellent structure and conciseness.

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 with multiple modes (production, custom domain) and statuses. The description compensates by directing the agent to read get_guides('publishing') for comprehensive details, which is a reasonable way to handle that complexity. Additionally, the schema covers the main parameters (though projectId lacks a description). The absence of an output schema is mitigated by the guide reference, making the definition reasonably complete for a complex 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 description does not discuss any parameters directly, but the input schema provides descriptions for 3 of 4 parameters (domain, domain_type, include_made_with_floot), covering 75% of them. The description's reference to get_guides for 'inputs' implies the parameters are non-trivial, and the schema already covers most semantics. Given the moderate coverage, a baseline of 3 is appropriate since no extra parameter meaning is added by the description.

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 core function: 'Publish the app to production or set up a custom domain.' It names the specific verb and resource and explicitly contrasts with the sibling republish_app, making it easy for an agent to distinguish between 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?

The description gives explicit usage conditions: 'call when the user wants the app live or asks about a domain.' It also provides a when-not-to-use rule: 'Already-published apps needing a rebuild use republish_app instead.' Additionally, it directs the agent to read get_guides('publishing') before the first call, which fills in remaining usage details.

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 are sparse (readOnlyHint false, destructiveHint false), so the description carries the burden. It discloses that the helper is generated, warns against hand-editing, and explains the workflow for fixing loose types. It does not explicitly state whether it modifies the database, but it implies a side effect by writing a file. This adds meaningful context beyond annotations, though it could be more explicit about what files are written or if any DB changes occur.

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

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

The description is long but every sentence adds value. It front-loads the core purpose, then gives usage context, then actionable advice about generated code. It is not bloated despite its length; it's efficient and well-structured for a tool with this complexity.

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 there is no output schema and the tool involves multiple steps (introspection, helper generation, working with different SQL dialects), the description covers the key points: when to use, optional helper_name, and the pitfall of editing generated code. It does not detail the return value or file paths, but that's likely not critical for an agent's correct invocation. It's quite complete for its 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?

Schema description coverage is 0%, so the description must compensate. It explains helper_name clearly (generates helper for additional/external database) but does not elaborate on database or projectId. Given three parameters and only one explained, the description adds value but incomplete. Baseline for low coverage would require more, so a 3 is fair.

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 introspects the database and writes a typed schema helper, and specifies it matches the project's existing approach (kysely vs drizzle). It distinguishes itself from execute_sql by noting it's usually not needed after schema changes auto-pull. This is a specific verb+resource with clear differentiation from a key sibling.

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?

Explicit guidance is given: use it to manually refresh or with helper_name for additional databases, and avoid it after execute_sql since schema-changing statements re-pull automatically. This provides clear when-to-use and when-not-to-use instructions, exceeding simple context hints.

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 description is not required to repeat safety. It adds value by disclosing the return format ('Returns JSON: {rows, rowCount, command, truncated?}'), multi-statement behavior ('{results: [...]}'), and explicitly restating write rejection, going 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, efficient sentence that front-loads the core purpose ('Run a READ-ONLY SQL query') and packs all essential information without redundancy. Every clause earns its place, including return format and parameter guidance.

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 SQL query tool, the description covers all needed aspects: read-only nature, write rejection with the alternative, return format (including multi-statement variant), and the database parameter condition. There is no output schema, so the return description fills that gap. Nothing critical is missing for an agent to invoke the tool correctly.

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

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

With schema coverage at 0%, the description compensates by explaining that query is a SQL statement and database is optional with a specific condition for when to pass it. Although projectId is not explicitly described, it is a standard identifier and its purpose is implied. The description adds meaningful semantics to parameters beyond the bare 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: 'Run a READ-ONLY SQL query against the project's Postgres database'. It also explicitly differentiates from the sibling execute_sql by noting 'Writes are rejected — use execute_sql for those', making the 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?

It gives clear guidance on when to use this tool versus the alternative: 'Writes are rejected — use execute_sql for those'. It also provides conditional usage for the database parameter: 'Pass database only if the project has more than one', which is explicit and actionable.

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

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

Beyond the readOnlyHint/destructiveHint annotations, it details behavior for hosted assets (image vs text vs binary handling), the ≤3.75 MB image limit, and the conditional appending of type errors for .ts/.tsx files based on VM warmth. This is rich behavioral context the agent needs to correctly interpret return 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 long but densely informative, covering path conventions, asset behavior, diagnostics, and limits. Each sentence earns its place given the tool's complexity; the asset section could be slightly tightened without losing clarity.

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

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

For a read-only tool with no output schema, it explains return behavior for images, text, binaries, and type-error appending, plus the path scheme. Missing is explicit error handling (e.g., file-not-found), but 'cat -n style' implies file content with line numbers. Overall, it is comprehensive for the intended usage.

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

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

With 0% schema description coverage, the description compensates well: it explains the path scheme (item paths and asset paths), the offset/limit usage, and the diagnostics enum values ('off', 'wait', and implied 'auto'). It does not explicitly define projectId, but that is self-evident; limit/offset semantics are light but 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?

States a specific verb ('Read') and resource ('a file from a Floot project'), explicitly notes 'cat -n style' (line numbers), and the singular scope distinguishes it from the sibling read_files. The detailed path scheme further clarifies exactly what file types are covered.

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 clear usage context: 'Use offset/limit for large files' and explains the diagnostics parameter's behavior under different VM-warmth conditions (auto-appending errors, 'off' to skip, 'wait' to force). However, it does not explicitly contrast with read_files or write/edit siblings, so boundary inference is left to the agent.

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

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

Beyond the basic readOnlyHint and destructiveHint annotations, the description discloses performance benefits (one round-trip), output format (cat -n style with headers), type-error appending behavior with conditions (warm VM, diagnostics options), and output capping with a listing fallback. No contradictions with annotations.

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

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

A single dense paragraph that front-loads the primary benefit and usage guidance, then methodically covers mechanics: path rules, output format, diagnostics, and output cap. Every sentence contributes meaning; no fluff 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?

With no output schema, the description supplies all essential behavioral details: how files are returned, diagnostics behavior, output capping and fallback. All four parameters are addressed, and the tool's edge cases are specified sufficiently for an agent to invoke it correctly.

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

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

Schema description coverage is 0%, so the description compensates: it explains paths (up to 20, same item scheme as read_file, cdn asset support), diagnostics enum values (off to skip, wait to force, implying auto as default), and limit indirectly via the output cap description. However, the limit parameter's direct effect is not explicitly tied to the cap, leaving slight ambiguity—hence a 4 rather than 5.

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 ('Read MULTIPLE files') and resource ('Floot project'), and explicitly contrasts with the sibling read_file (repeated calls for single files) by highlighting the efficiency of one call. This clearly distinguishes it from the most similar sibling.

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

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

It explicitly advises 'Prefer this whenever you need several files together' and gives concrete examples (endpoint + .schema.ts + hook). It also explains when to skip diagnostics (diagnostics:'off') or force them (diagnostics:'wait'), and describes the fallback for oversized batches, providing clear selection and invocation 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?

The description adds the key behavioral fact that this operation is 'record-only; nothing runs', which communicates that it does not execute code or have side effects on the environment. This goes beyond the annotations (readOnlyHint=false, destructiveHint=false) by clarifying the mutation is restricted to a record. No contradiction with annotations.

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

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

A single sentence that is concise, front-loaded with the action and resource, and ends with the critical behavioral note. No redundant words or repetition; every part adds value.

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

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

The tool is simple (two required parameters) and the description covers the core operation and its non-execution nature. Since there is no output schema, the description doesn't need to explain return values. It is adequate for a record-only update, though it lacks details on error behavior or what happens if a package doesn't exist, which are minor given the 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?

Schema description coverage is 0%, so the description must compensate. It gives context for the 'packages' parameter by mentioning 'npm packages', but it does not explain 'projectId' at all. The description provides only a partial hint about parameters, insufficient for an agent to correctly construct inputs without external knowledge.

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 ('Remove'), a resource ('npm packages from a Floot project's dependency record'), and implies a domain (Floot project). It clearly distinguishes from the sibling add_dependency by the verb and context. No ambiguity about what the tool does.

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 mentions 'record-only; nothing runs' which is a usage caveat indicating safety, but it does not explicitly state when to choose this tool over alternatives (e.g., 'use this instead of edit_file'). The purpose is clear from the name and sibling context, but explicit guidance on condition of use is missing.

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

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

Annotations only state readOnlyHint=false and destructiveHint=false, so the description carries the burden of disclosing behavior. It does so by revealing the rewrite side effect, atomic batch application, and chain resolution. However, it doesn't mention error handling, rollback, or permissions, which are less critical but still relevant for a mutating 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?

The description is dense but every sentence adds value: main function, format example, preference rationale, constraint, and batching semantics are all present without fluff. It is front-loaded with the core purpose, though a bit long for a simple rename 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?

For a rename tool without an output schema, the description covers the essential aspects: what it does, how to specify renames, constraints, and batch behavior. It lacks return-value details and error-case notes, but these are often predictable. Given the tool's complexity, this is sufficiently 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 coverage is 0%, so the description must compensate. It clarifies the 'renames' parameter with an example and the no-extension rule, which adds meaning. But it says nothing about 'projectId' or 'expected_version', leaving those under-specified for a tool with 0% schema coverage. The partial clarification earns a middle score.

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

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

The description clearly states a specific action ('Rename one or more items') with a key side effect ('automatically rewrite every file that imports them'). It distinguishes from delete+create and implies a precise use case, making it easy to differentiate from sibling tools like copy_file or delete_file.

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

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

Provides explicit guidance: 'Preferred over delete+create', clarifies the required name format ('Use item names WITHOUT extensions'), imposes a constraint ('Same type only'), and explains batching behavior ('atomic in ONE pass' with chain resolution). This tells the agent exactly when and how to use the tool versus 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 carry destructiveHint=true and readOnlyHint=false, and the description aligns with those (rebuilding a live production app implies an overwrite). It adds the useful 'LIVE production' scope context, but besides that it doesn't disclose much beyond what the annotations convey. No contradiction with annotations.

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

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

Two tight sentences with the core action front-loaded. Every clause earns its place: the action, the trigger condition, the alternative, and the pointer to the guide — 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 operation on a live app with a single required param and no output schema, the description gives the agent the key behavioral context, differentiates from siblings, and routes to a guide for deeper details. Minor gap: it never hints at what the response or side effects look like beyond the rebuild, but for this complexity it is largely sufficient.

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%: include_made_with_floot is documented in the schema, but the required projectId has no schema description, and the description does not compensate for it. The description adds no parameter-level guidance whatsoever, leaving the undocumented required parameter unelaborated.

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+resource ('Rebuild the LIVE production app with the current project code') that makes the operation unmistakable. It also draws an explicit distinction from the publish_app sibling, so an agent can tell the two apart without inspecting schemas.

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

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

States precisely when to call it ('after changes the user wants live') and names the exclusion condition ('the app must already be published; otherwise use publish_app'). It even points to get_guides('publishing') for further detail, leaving no ambiguity about selection.

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 (readOnlyHint=false, destructiveHint=false, openWorldHint=false) convey minimal behavior, so the description carries the full burden and delivers: it discloses blocking semantics (completes only when the user finishes the connect flow, never expires, should not be blocked on), side effects (POSTGRES reuse seeds helpers/db and installs the query stack), idempotency (re-calling returns the same pending request), and the post-condition (returns env var names, never secret values). No contradiction with annotations.

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

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

The description is a dense, single run-on paragraph exceeding 1,000 characters with many nested clauses and parentheticals (e.g. 'on terminal hosts with shell access open it in the user's default browser yourself and paste the URL as plain text'). The ordering is logical and the purpose is front-loaded, and every sentence earns its place given the tool's complexity, but the lack of visual structure (bullets, headers) makes it hard to parse for an agent scanning quickly.

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 high complexity and minimal annotations, the description is remarkably complete: purpose, exclusions, reuse path, side effects, connect-link display behavior per host type, non-blocking guidance, secret-handling policy, and return semantics (env var names, never values). With no output schema, it correctly explains what the call returns. Nothing an agent needs to call this correctly is missing.

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

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

Schema coverage is 67% with solid param descriptions for name, instructions, secret_env_vars, and optional_env_vars. The description adds meaning beyond the schema by explaining the GENERIC type semantics (type GENERIC naming env vars via secret_env_vars), clarifying the optional_env_vars vs secret_env_vars distinction, and revealing the POSTGRES side effects. projectId is self-evident ('this project'). Strong compensation on top of already-decent schema 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 states a specific verb+resource — requesting the user's own external credential (API keys, connection strings) for a project — and immediately distinguishes itself from provision_resource by exclusion ('NOT for Floot-managed resources...use provision_resource for those'). An agent can unambiguously tell this tool apart from its siblings without opening the schema.

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

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

Exceptionally explicit: names the alternative (provision_resource) and the exact condition selecting it, plus the 'REUSE FIRST' rule referencing list_resources section 2. It also gives operational timing guidance — request EARLY, don't block, check between tasks, never ask for a secret in chat. This is the gold standard of when-to-use/when-not-to-use documentation.

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 are minimal (readOnlyHint, destructiveHint), but the description discloses extensive behavior: it returns a jobId, requires polling get_job_status, stays running until upload, and returns a publicUrl. It also explains technical constraints like the 3 MB inline cap and that browser uploads are never egress-blocked. This fully compensates for the sparse annotations and adds no contradiction.

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

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

Despite its length, the description is tightly structured: it front-loads the core action, then systematically covers use cases, return behavior, user interaction guidance, and alternatives. Every sentence carries necessary information—there is no fluff. The density is justified by the interactive complexity of 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?

Given the tool's interactive nature and lack of an output schema, the description covers all necessary context: return contract (jobId + publicUrl via polling), failure modes (3MB cap, egress), and user-communication requirements. It even addresses edge cases like attachments not reaching MCP servers. No information an agent needs to invoke and use this tool correctly is missing.

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

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

Schema coverage is 50%: only the 'description' parameter has a description, while 'projectId' has none. The tool description does not explicitly explain projectId's purpose or format beyond its name, relying on self-evident naming. It does provide guidance on crafting the description parameter (e.g., 'tell the user in a sentence why you're asking'), but it doesn't fully compensate for the missing projectId documentation. The marginal value is adequate, not exceptional.

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 shows an inline upload card to obtain a file from the user, which lands in hosted assets and returns a publicUrl. It distinguishes itself from siblings by explicitly naming the alternative paths: 'For files you hold yourself, use upload_asset; for AI-generated imagery, use generate_image.' This makes the purpose and differentiation crystal 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 provides explicit when-to-use guidance, enumerating three scenarios (attached images, local files, user-provided files that can't egress) and explicitly exclusions for upload_asset and generate_image. It also instructs the agent to explain to the user why the file is needed and to ask them to confirm completion. This is a model of usage clarity.

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 description adds useful context beyond the destructiveHint=true and readOnlyHint=false annotations: it details the execution environment (live DOM, no iframe), the return-value contract (string from the async function), and the fail-fast behavior when no browser is connected. It also notes that simple clicks work while typed input is unreliable, setting accurate expectations.

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 lengthy but each sentence adds value: it front-loads the critical execution model, then logically covers alternatives, code requirements, and limitations. No redundancy; the structure helps an agent quickly grasp the tool's scope and constraints.

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 no output schema, the description explains the return value clearly (the string returned from the function). It covers prerequisites, failure behavior, and appropriate use cases, making it sufficient for an agent to invoke correctly. Minor gaps like error handling or `_floot.*` helper details are not critical for basic usage.

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

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

The schema already covers the 'code' parameter in detail (format, example, restrictions), and the description reinforces it. However, 'projectId' is only implicitly tied to the requirement that the project be open in the editor; there is no explicit definition of what value to pass. With 50% schema coverage, the description partially compensates but leaves projectId under-explained.

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 it runs a TypeScript snippet in the running app's live DOM, naming the verb and resource precisely. It differentiates from run_code_in_vm by the return-value behavior and positions itself as the canonical way to read the app's DOM, distinguishing it from siblings like fetch or execute_sql.

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

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

It provides explicit when-to-use guidance: 'prefer run_code_in_vm for anything that doesn't need the DOM' and 'use THIS tool for anything inside the app' vs external automation. It also advises against multi-step e2e and typed input, directing the agent to leave those to the user, giving clear exclusions.

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 indicate destructiveHint=true and readOnlyHint=false, but the description goes far beyond: it discloses the isolated temp dir, lack of project env vars/secrets, rate-limiting behavior, and the exact behavior of _floot helpers. It also warns against destructive SQL usage in this tool and directs those to execute_sql. This is rich behavioral context that fully complements the annotations with no contradiction.

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

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

The description is long, but every sentence carries essential information: purpose, constraints, alternatives, helper APIs, and rate-limit warnings. It is front-loaded with the core action and then systematically details behavior. The structure is clear with paragraphs and bullet-like details, though it is dense enough that a shorter version might be possible without losing value.

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

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

Given the tool's complexity (many helpers, rate limiting, isolation, and edge cases), the description is remarkably complete. It covers return formats, helper signatures, special constraints like 'prefix MUST start with public/' and the exact rate limit numbers. There is nothing an agent needs to know to call this tool correctly that 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?

The schema provides no descriptions for any of the three parameters (coverage 0%), so the description must compensate. It explains that `code` is a Node.js snippet and how ESM/CJS work, but it does not explain `projectId` or `timeout_seconds` at all. Because two of three parameters remain unexplained, the description fails to provide complete parameter semantics.

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 precise action and resource: 'Run a Node.js snippet on the project's compute VM' and immediately clarifies it is headless, distinguishing it from the browser-based alternative. It names the sibling tool (run_code_in_browser) and explains the key difference, so an agent can tell them apart without opening either schema.

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

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

The description gives explicit guidance on when to use this tool vs. others: use _floot helpers or /_api/* endpoints for secrets/env/DB access, use execute_sql for destructive SQL, and use run_code_in_browser when project file imports are needed. It also warns about rate limits and recommends batching instead of looping, making routing decisions unambiguous.

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 indicate readOnlyHint=true and destructiveHint=false, and the description adds substantial behavioral context beyond that: it runs headlessly on a VM with jsdom, details the testing environment limitations, explains that @floot/* modules are skipped, and describes the output format (per-file PASS/FAIL). This transparency helps the agent anticipate side-effects and constraints without contradicting 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 fairly long but densely packed with useful information. It front-loads the core action and then logically covers scope, limitations, and customization. Every sentence adds value, though it could be slightly more structured (e.g., bullet points). The length is justified by the tool's complexity, so it earns a 4 rather than a lower score.

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

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

Given the tool's complexity (test execution, environment constraints, multiple spec types), the description covers all essential aspects: what runs, how it runs, what to expect (PASS/FAIL), default exclusions, and how to override. It lacks an output schema but compensates with descriptive output information. An agent would know exactly what to do and what to expect, making this 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 0%, so the description must compensate for both parameters. It explains 'paths' well ('pass paths to run specific spec files') and implies that projectId identifies the project. However, it does not explicitly describe projectId's format or purpose, leaving some ambiguity. Since the tool is project-specific, projectId is likely obvious, but the description could be more explicit. Given the limited compensation, a score of 3 is fair.

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 ('run') and resource ('Jasmine spec files'), with precise scope ('helpers/*.spec.tsx', headlessly on VM with jsdom). It clearly distinguishes itself from siblings like run_code_in_vm or typecheck by focusing exclusively on test execution. The title and name align, and the description leaves no ambiguity about the tool's function.

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 explicit guidance on when and how to use the tool: defaults to all spec files except hook specs, pass 'paths' to run specific files including hook specs. It also explains constraints (fetch throws, no env secrets, @floot/* skipped) that inform usage decisions. This is thorough and actionable, covering both default behavior and overrides.

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 tool's safety profile is covered structurally. The description adds useful context (the tool captures a visual snapshot for inspection/debugging) but does not disclose potential caveats like whether the app must be running, the freshness of the screenshot, or any rate limits. Given the annotation coverage, the description adds some value but not deep behavioral detail.

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, tightly written sentence that front-loads the core action ('Capture a screenshot') followed by explicit usage guidance. Every word serves a purpose; there is no fluff, redundant phrasing, or unnecessary detail. It is a model of conciseness.

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 with only one parameter and no output schema. The description explains when to use it and what it does, but it omits any explanation of the projectId parameter and does not mention potential prerequisites (e.g., app running). While annotations cover safety, the lack of parameter guidance and any return expectations leaves gaps that an agent might need to infer, making it adequate but not fully self-contained.

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 a single required parameter 'projectId' with no description, and the schema_description_coverage is 0%. The description does not mention projectId at all, leaving its purpose, format, or how to obtain it entirely unexplained. With zero coverage and no compensatory text, the parameter semantics are severely deficient.

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 'Capture a screenshot of the user app' and specifies the resource (the user app preview). It distinguishes the tool's purpose from siblings like 'get_preview_url' (which provides a URL, not a visual) or 'navigate_preview' (which changes the view). The mention of 'want to SEE what the app currently looks like' and 'debug the app' gives concrete, concrete use cases.

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 explicit guidance on when to call this tool: 'whenever you want to SEE what the app currently looks like' or to debug. This gives a clear context for selection, though it does not explicitly mention alternatives or when-not to use, which prevents it from being a 5. The usage intent is unambiguous enough for an agent to decide correctly.

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, covering the safety profile. The description adds genuine value beyond the annotations by disclosing the return behavior ('Returns result ids usable with fetch'), which tells the agent the output can be chained into fetch. This is useful behavioral context not present 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?

Three tight sentences with zero filler. The purpose is front-loaded in the first sentence, the output coupling in the second, and the alternative routing in the third. Every sentence carries weight.

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 low-complexity single-parameter read-only tool, the definition covers purpose, target scope, output format, and sibling routing. With readOnlyHint/destructiveHint annotations supplying the safety profile, little is missing. Only minor gaps like pagination or result limits remain, which are not critical for a search tool of this shape.

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

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

Schema description coverage is 0%, so the description bears the full burden of explaining the query parameter. It implies query is free-form search text by saying the search covers projects and their code, but it adds no detail on format, syntax, or matching behavior. This is thin compensation for an undocumented parameter.

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 ('Search'), a concrete resource ('your Floot projects and their code'), and explicitly names the sibling tools it is not (list_projects, search_code). An agent can distinguish it from search_code and list_projects at a glance, which is the core requirement for purpose clarity.

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?

Names the alternatives explicitly ('list_projects enumerates projects and search_code does code-level search') and signals when they are the better choice ('For richer options'). It lacks a crisp positive 'use this when...' condition, but the alternative-routing guidance is clear and useful.

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 description adds value by disclosing the result format (file:line excerpts plus filename matches) and the 40-result cap. It does not contradict annotations and provides useful behavioral details about output and 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, dense sentence that front-loads the purpose (search project files) and immediately provides key options (string or regex, glob filters) and output characteristics (file:line excerpts, 40-result cap). No filler or redundant statements; every clause adds 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 that annotations cover the safety profile (non-destructive, read-only), and the description states the return format and result cap, an agent has enough information to invoke this tool correctly. The parameters are adequately described, and the optional glob filtering is explained with examples. No missing critical information for a search operation.

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

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

With 0% schema description coverage, the description compensates by explaining the query parameter (string or regex), the regex boolean (interpretation toggle), and providing examples for the glob filter array. The projectId parameter is implied via 'a Floot project' but not explicitly detailed, which is a minor gap. Overall, the description adds meaningful semantics beyond the bare 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 ('Search'), a specific resource ('a Floot project's files'), and key capabilities (string or regex, glob filters). It distinguishes from the sibling 'search' by specifying 'project's files' and 'file:line excerpts', making its 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?

The description provides clear context: it is for searching code files within a project, with optional glob scoping. However, it does not explicitly contrast with sibling tools like 'search' or 'read_file', or state when to avoid this tool. Given the tool name and description, an agent can infer its role, but explicit exclusions would improve it.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, covering the safety profile. The description adds the key behavioral fact that 'type errors don't block the app from running', which is useful context beyond the annotations. However, it does not describe what the tool outputs (e.g., exit codes, error list), so the additional disclosure is limited.

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 concise sentences, with the core purpose first and a behavioral note second. No wasted words or redundant details. It is appropriately sized for a simple tool, though the sentence order could optionally front-load the non-blocking behavior.

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 typecheck tool with annotations covering safety, the description covers the basic purpose and a key behavioral nuance. However, it omits semantics for the optional 'paths' parameter and does not describe the return value or how errors are surfaced. Given the low schema coverage, this is a notable incompleteness.

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%. The description implies projectId from 'the project' but provides no explanation of the optional 'paths' parameter. An agent cannot infer whether 'paths' restricts typechecking to specific files or directories. The lack of parameter documentation is a significant 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 clearly states the tool's action ('Typecheck the project') and provides implementation detail ('incremental tsc on the project VM'). It is specific about the resource (project) and the operation, distinguishing it from siblings like run_tests or run_code_in_vm without explicit differentiation, but the purpose 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?

No guidance on when to use this tool versus alternatives. It does not mention that it is lightweight or incremental compared to a full typecheck, nor does it reference any sibling tool or condition. The note about type errors not blocking the app is informative but not a usage directive.

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, so the description reinforces that. It adds the specific behavior of releasing the subdomain and the requirement for user confirmation, which goes beyond the annotation. It also references get_guides for further details, providing additional context for the agent. While not exhaustive (e.g., data retention), it sufficiently discloses the destructive nature.

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. The core action and warning are front-loaded, and the reference to get_guides is a concise way to point to further details. 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?

For a simple one-parameter tool with a clear destructive hint, the description covers the essential action and the confirmation requirement. It also references the guide for deeper instructions. It does not mention side effects beyond subdomain release, but given the destructiveHint and the pointer to get_guides, the description is adequately complete for an agent to call it correctly, though it could be slightly richer.

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

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

The schema has one parameter (projectId) with zero schema description coverage, meaning the description does not explain it. The tool description never mentions projectId, so it fails to compensate for the coverage gap. Even though the parameter name is self-explanatory, the description adds no clarity about its purpose or format.

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 ('take offline') and the resource ('published app' plus 'subdomain'), making it obvious this is the inverse of publish_app. It also differentiates from siblings like republish_app by specifying the offline action and subdomain release.

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 a strong usage context by flagging the action as destructive and instructing to confirm with the user first. It also points to get_guides('publishing') for additional detail, but it does not explicitly name alternatives or conditions when not to use this tool. The sibling list suggests obvious opposites (publish_app, republish_app) but no explicit exclusion is stated.

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

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

The description discloses several behavioral traits beyond what annotations provide: invalid keys/values are reported and skipped, changes are not live until the next publish, and iOS/Android settings have post-publish limitations. Since annotations only give hints (readOnlyHint=false, destructiveHint=false) and do not cover these details, the description significantly enriches the agent's understanding of how the tool behaves.

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

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

The description is long but every sentence adds necessary information: key list, validation behavior, timing, and post-publish alternatives. It is front-loaded with the core purpose and then dives into specifics. While dense, it is not redundant or fluffy, so the length is justified.

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

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

For a write operation with complex side effects, the description covers all necessary context: what fields can be updated, how invalid values are handled, when changes become effective, and what to do after publish. It also points to get_guides for further details on iOS/Android specifics. Nothing an agent needs to call this tool correctly is missing.

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

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

The input schema provides no descriptions for the parameters (0% coverage), so the description carries the full burden. It explains the 'updates' object in detail, enumerating all valid keys (title, description, iconUrl, splashUrl, mobileAppId, enableSSR, flootAiDisallowed, iOS Info.plist keys, boolean keys) and their types, plus special handling (null to remove, booleans). This fully compensates for the schema's lack of semantic detail.

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 'Update project settings' and lists the specific keys, making the verb and resource unambiguous. It does not explicitly name a sibling tool to distinguish from, but the scope is specific enough that an agent could infer it is distinct from tools like create_project or list_projects.

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 explicit guidance on when to use the tool and when not to: it states that changes take effect only after the next publish, and after the first iOS/Android publish, the user should edit files directly instead. It also names the alternative tools (write_file/edit_file and get_guides) and gives conditions, which is exactly the kind of operational guidance expected.

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 indicate readOnlyHint=false and destructiveHint=false, which are consistent with an upload operation. The description goes far beyond, detailing what happens with each mode, the 3MB/100MB caps, the short-lived presigned URL, the egress block implications, and the exact behavior for the `file` parameter in ChatGPT. It explains the full mechanics 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 long but well-structured, starting with the core purpose, then branching into modes and edge cases. Every sentence adds necessary information; there is no fluff. It could be slightly more compact, but the complexity of the tool justifies the length. It remains readable and 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 complexity (6 parameters, nested objects, no output schema), the description covers all essential contexts: mode selection, size limits, egress blocking, alternative tools, and error handling. No critical information is missing, making it fully complete for an agent to call correctly.

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

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

While schema coverage is 67%, the tool description adds substantial meaning to every parameter. It explains when `file` is required vs. other modes, how `content_base64` and `size_bytes` must match, the purpose of `content_type`, and the optional status of fields in `file`. It clarifies relationships and provides context the schema lacks, making parameter usage error-proof.

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 exactly what the tool does: uploads a binary asset to the project's hosted storage. It clearly distinguishes itself from related tools like card_upload_asset, request_user_upload, and generate_image, and explains the three modes. Specific verbs and resources make 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?

The description provides explicit guidance on when to use each mode, when to delegate to request_user_upload (for chat attachments), and when to use generate_image for fresh AI imagery. It also discusses sandbox egress blocking and advises path-switching over retrying, effectively preventing misuse. No ambiguity remains.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds value by noting that annotations expire after ~1 day and that the tool returns an image. It does not mention error cases (e.g., expired annotation), but the extra context is useful beyond what annotations provide.

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

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

Three short sentences with no fluff. The most important info (what it does and where the id comes from) is front-loaded, and the expiration note is placed at the end. Every sentence earns its place.

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

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

For a simple read-only tool with two string parameters and no output schema, the description covers the main behavior and return value. However, it leaves projectId undefined and does not mention what happens when an annotation expires or if the id is invalid. These gaps reduce completeness for an agent trying to use it reliably.

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 compensate. It gives meaning to annotationId by pointing to get_current_context, but projectId is left completely unexplained. This partial compensation is insufficient for a required parameter, but the one semantic clue is helpful.

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 ('View a screenshot annotation') and resource ('the user drew on the app preview'), and clarifies the return value (annotated image). It does not explicitly distinguish from siblings like get_current_context, but it implies a complementary relationship rather than a replacement, so it is clear enough.

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

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

The description gives a key usage hint: 'annotationId comes from get_current_context', which tells the agent to call that tool first. However, it does not explicitly state when to use this tool over alternatives, nor any exclusions or conditions. The guidance is implied rather than explicit.

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

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

Adds valuable detail beyond annotations: literal content writing, path validation rules, concurrency detection via expected_version, and the special module.css side effect. Annotations only say it's not read-only and not destructive, so the description carries extra behavioral information. No contradictions.

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 about five sentences, front-loaded with the core action and then adding necessary nuances. No filler, every sentence earns its place. It is well-structured and easily scannable.

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?

Covers purpose, path rules, concurrency, and a special behavior. It lacks an explicit return value description (no output schema) and some edge cases (e.g., if expected_version is omitted), but overall it is more complete than typical write tools. The pointers to read_file help fill 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 description coverage is 0%, so the description must explain each parameter. It explains path (item scheme) and expected_version (concurrency check), but projectId is not mentioned and content is only described as 'written literally', which is insufficient. Coverage is partial, leaving half the parameters unexplained.

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 explicitly states 'Create or fully overwrite a file' – a specific verb and resource. It distinguishes from siblings (edit_file, apply_patch) by saying 'fully overwrite' and also describes the special CSS behavior, 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?

It gives clear guidance on path scheme (see read_file) and concurrency (pass expected_version). The phrase 'fully overwrite' implicitly contrasts with partial edits, and the CSS example illustrates a specific use case. It doesn't explicitly list when not to use it, but the instructions are enough for an agent to decide.

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