floot

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

Very rich disclosure beyond the annotations: atomicity, that unmatched Delete/Move sections are skipped or rejected rather than applied, that history records and revert is possible, and that truncated patches fail as a whole. The annotations only say readOnly=false/destructiveHint=false/openWorld=false, so this added context is genuinely informative; it stops short of describing the response shape or conflict 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?

One dense paragraph, but the most decision-relevant facts (verb, atomicity, patch format, then limitations, then size cap) are front-loaded and each sentence carries operational weight; length is justified by the format's complexity, though it could be broken into clearer blocks.

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

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

For a complex mutation tool with no output schema, the description covers format, atomicity, failure modes, undo, and size limits, and hints at result content (skipped sections are 'listed in the result'). The remaining gap is the undocumented expected_version parameter and the absence of a conflict/version-mismatch explanation.

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% for 3 parameters, and the description thoroughly documents the syntax of the `patch` string value (envelope, Add File/Update File hunks, anchors, End of File) but never mentions projectId or expected_version, the latter being an optimistic-concurrency control an agent could easily mis-set.

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

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

States a specific verb and resource ('Apply a V4A patch to a Floot project') plus the key scope ('create and update multiple files in ONE atomic operation'), which immediately separates it from single-file siblings like write_file and edit_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?

Explicitly routes the agent away from the wrong tools: Delete File sections are skipped and delete_file is named as the alternative, Move to is rejected in favor of rename_file, Add File on the same path is given as the wholesale-replace idiom, and oversized changes are told to be split across calls.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the safety profile is known. The description adds substantive context beyond that: the operation is irreversible and non-resumable, the user must create a new request, and only pending (not completed) requests qualify. It doesn't cover auth/permission requirements, which keeps it just below a 5.

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

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

Front-loads the verb and the three request sources, then layers constraints and the use case, so the critical routing information appears first. It is slightly dense with em-dash clauses but every sentence carries information.

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

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

For a destructive mutation with no output schema and no annotations covering reversibility, the description supplies the missing essentials: what is being destroyed, that it is final, preconditions, and the triggering user intent. The unexplained projectId parameter is the main remaining gap.

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 full explanatory burden. It hints that jobId originates from screenshot_preview ('jobId from that tool'), but that parenthetical is ambiguous for the credential/custom-domain cases, and projectId is never explained at all. Half the parameters remain undocumented in both schema and 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?

States a specific verb (withdraw/cancel) and resource (a pending request), and enumerates exactly the three request sources it operates on — request_external_resource, publish_app, screenshot_preview — naming sibling tools directly. An agent can distinguish this from other mutation tools 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?

Gives clear context for use ('when the user says to stop or they don't want to proceed') and preconditions ('only pending requests can be cancelled'). It stops short of naming alternate tools for genuinely different situations, but the operation is narrow enough that this is minor.

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?

Annotations only declare the safety profile (not read-only, not destructive, not open-world). The description goes well beyond: it discloses that projects are pre-seeded with a shared component library, that initial_prompt becomes an editable system prompt on disk, that it is served back as <project-instructions>, that a preview card renders, and critically that a fresh project is EMPTY until pages are written.

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

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

Front-loads the core action and return value in the first clause, then layers the prompt semantics and workflow guidance. Dense but nearly every sentence carries information; the closing playbook sentence is long yet genuinely actionable.

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

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

With no output schema, the description carries the return burden and does so (id plus live preview card). Combined with the prompt-grounding and empty-project details, an agent has everything needed to call it correctly and know what to do next.

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 initial_prompt is documented). The description compensates strongly for that parameter — it explains what the prompt should contain (app purpose and audience, preserving user wording), where it is stored, and how it grounds the project — though the `name` parameter remains unexplained beyond the schema.

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

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

States a specific verb+resource ('Create a new Floot project') and immediately distinguishes it from siblings like list_projects by naming the returned artifact (the id) and the pre-seeding behavior.

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?

Explains the workflow context — a session normally continues into get_guides("design") and writing the first page rather than ending at the preview card. It gives clear when-to-use context but does not spell out when NOT to create a project or name a specific alternative tool.

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

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

Annotations already 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 already declare destructiveHint=true and openWorldHint=true, but the description adds critical operational context: the user-approval flow, automatic schema helper re-pull on DDL, default single-transaction wrapping, and a 90-second kill timeout. This is exactly the behavioral detail annotations cannot convey.

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

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

Front-loaded with the core purpose and statement types, then layers operational details. It is dense and somewhat long, but nearly every sentence earns its place by conveying approval, transaction, or timeout 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?

With no output schema, the description itself closes the loop by explaining that schema-changing statements return the updated typed schema. Transaction handling, timeout, multi-DB selection, and approval are all covered, leaving no significant gaps for a high-risk write tool.

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

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

Schema coverage is only 25% (just no_transaction documented), so the description must compensate. It explains `database` semantics (needed only for multi-database projects) and reinforces `no_transaction`, though `projectId` and the `query` string itself receive no explicit elaboration.

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+resource ('Run a WRITE SQL statement against the project's Postgres database') and enumerates the statement classes (CREATE/ALTER/INSERT/UPDATE/DELETE/DROP, migrations). The write framing clearly distinguishes it from the read sibling query_database.

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?

Explains exactly when to use it (write statements), when `database` is needed ('only if the project has more than one'), and when `no_transaction` applies (VACUUM, CREATE INDEX CONCURRENTLY). Also tells the agent a separate pull_database_schema call is unnecessary after schema changes.

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 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?

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?

Annotations declare readOnly/destructive=false, and the description substantially extends them: the URL embeds an access token, must be shared exactly as returned, is view-only with no Floot login, live-updates during edits, and the result also exposes a sandbox API base that is NOT user-facing. This is exactly the kind of behavioral context annotations cannot convey, 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 and most sentences carry real signal (token behavior, live updates, sandbox API distinction). It is dense and somewhat over-long, and the trailing 'Floot hosts the app' framing sentence is only marginally load-bearing, but there is little true filler.

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

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

No output schema exists, yet the description explains what the result contains (preview card, preview link, sandbox API base) and how each should be used. Combined with the usage and security notes, an agent has everything needed to invoke and interpret 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% and the sole parameter (projectId) is never mentioned in the description. However, projectId is a self-evident, unambiguous single required argument, so the practical risk is minimal. Not a perfect score because the description technically leaves the parameter to the schema.

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

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

States a specific verb and resource: 'Show the user a live preview card and return the preview link.' It goes further, distinguishing itself from create_project (whose result already includes the card) and from publish_app (production publishing). An agent can place it precisely among the many 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?

Explicit timing guidance ('On an EXISTING project this is typically called EARLY, before the first change'), an exclusion ('It is not needed right after create_project'), and a named alternative for the production case ('publish_app publishes it to production'). Covers when, when-not, and the alternative.

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 mark the call read-only/non-destructive; the description adds substantial behavior: paid vs plan distinctions, fair-use unlimited semantics, boostUntil timing, and the fact that mobileBuild finishes after its publish job. No contradiction with the readOnlyHint.

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

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

Every detail serves a purpose, but it is delivered as one long, dense run-on paragraph with deeply nested parentheticals. The core is front-loaded, but bulleted field breakdowns would make it far more 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?

With no output schema, the description carries the full burden of explaining return values, and it does so thoroughly: every response field, its possible values, and its caveats are described. An agent has enough to interpret the snapshot and decide next actions.

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?

There is one parameter, projectId, with 0% schema description coverage. The description repeatedly ties the data to 'a project' and 'the project's latest', giving semantic context, but it never states the expected identifier format or type beyond the schema's plain string.

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 precise verb and object — 'Read-only publish snapshot for a project' — then enumerates the exact fields returned. It also differentiates from sibling outputs by stating it is 'the ONLY tool that reports attached custom domains'.

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 gates: read before asserting a domain is connected/unattached, read before passing mobile: true, and check before publish_app to know whether it will publish fresh. It also warns against concluding domains are unattached from any other output, effectively excluding alternatives.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, lowering the burden on the description. The description adds useful behavioral context by specifying it returns a virtual file tree with sizes, dependencies, version, and metadata fields, and clarifies that update_project_metadata performs mutations. 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 long single paragraph but information-dense; every clause contributes value, and the second sentence provides operational guidance. A bulleted list would improve scannability, but there is no filler or redundancy.

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

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

For a read-only listing tool with no output schema, the description thoroughly enumerates what the response contains: file tree, dependencies, expected_version, and detailed metadata fields. It even tells agents how to use the version value with write tools, making the definition effectively complete 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%, and the description does not explain projectId beyond implying a project is selected. The property name is self-explanatory, so the gap is minor, but the description still adds no parameter-level meaning and does not compensate for the missing schema 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 uses a specific verb ('List') and clearly identifies the resource: a Floot project's virtual file tree, dependencies, version, and project metadata. It also distinguishes itself from update_project_metadata by stating that this is the lookup tool while update_project_metadata changes those settings.

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 says 'This is where to look up those settings' and names update_project_metadata as the sibling that changes them, giving agents a clear when-to-use signal. It does not enumerate all exclusions, but the primary usage context is 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, 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?

Goes well beyond the annotations (readOnlyHint=false, destructiveHint=false, openWorldHint=true) by disclosing that Floot mints all secrets server-side, that the tool seeds working code, that it is idempotent (re-running returns the existing resource and skips existing seed files), and that app-connection requires an in-dialog user confirmation.

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

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

Front-loads purpose and scope before the bullet list. The length is driven by 11 enum values that each need disambiguation, so most sentences earn their place, though the dense prose on google-integration and app-connection could be trimmed slightly.

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

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

For a mutating, no-output-schema tool this covers side effects (minted secrets, injected files, service worker), idempotency, cross-app prerequisites, and the confirmation dialog. An agent has everything needed to call it correctly.

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

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

Schema coverage is 60%, and the description compensates by explaining what each resource value produces (env vars like FLOOT_DATABASE_URL, JWT_SECRET, injected pages/helpers) and by flagging that unlisted enum values are beta-gated. It also clarifies app_target/app_functions constraints, though projectId remains undocumented.

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

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

Opens with a specific verb and resource ('Provision a Floot-managed backend resource for the project') and immediately scopes it as fully server-side. The bulleted enumeration of each resource type makes it unmistakable against siblings like add_dependency or request_external_resource.

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 away from the tool when appropriate: 'For a user's OWN external key ... this is NOT the tool — use request_external_resource instead,' and 'SENDING email from the app is NOT a resource.' It also names the precondition for app-connection (write both apps first, connect, then publish) and points to get_guides for deeper flows.

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?

Compared to annotations (readOnlyHint=false, destructiveHint=true, openWorldHint=true), the description adds crucial behavioral context beyond structured fields: Stripe setup refusal behavior, Connect card generation for mobile, that publish always goes live, the editor publish form for web omissions, and the allowance mechanics on metered plans for mobile builds.

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

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

Front-loaded with the primary action and branches logically through mobile, payments, and domain cases. Some sentences are long and packed with conditional clauses (the mobile: true paragraph), but every clause carries operational value and nothing is redundant.

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

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

Given the complexity of the publish flow (different modes, payment setup gates, mobile build semantics, paid plan limits), the description covers the key decision points an agent needs to call correctly. It defers detailed modes and statuses to get_guides('publishing') and defers plan/allowance checks to get_publish_status, which is appropriate for preserving conciseness.

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

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

Although schema coverage is high (83%), the description adds substantial meaning beyond the schema: explains that omitting domain shows the publish form, that passing mobile: true triggers store build handling and updates the saved setting, and the refusal conditions when payments aren't set up. This is far richer than what the schema alone conveys.

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+resource (publish the app to production) and enumerates the distinct use cases: first publish, republish after changes, and custom domain setup. The agent can distinguish this from siblings like unpublish_app or get_publish_status.

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 pass mobile: true (iOS, Android, TestFlight, App Store, Google Play, native/mobile app). Explains onboarding edge cases (Stripe setup refusal, Connect card) and explicitly says never to ask the user test vs live. Points to get_guides('publishing') for first-call 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 (readOnlyHint=false, openWorldHint=true) are consistent with this, and the description adds substantial context beyond them: the helper is GENERATED, must never be hand-edited or cast around, and loose types must be fixed in the DATABASE then re-pulled. This is exactly the extra behavioral context the dimension rewards.

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

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

Front-loaded with the core action and the execute_sql relationship, then the usage cases. The closing type-fixing tangent is long and somewhat tangential, though genuinely useful, keeping this just short of a 5.

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-oriented tool with no output schema and 0% param coverage, the description covers behavior, usage, and constraints thoroughly. The main gap is that the three parameters' semantics and formats remain largely undocumented.

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's purpose (generate the helper for an additional/external database) and implies what `database` selects, but projectId and the exact semantics/format of `database` are left 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?

States a specific verb+resource: "Introspect the database and write a typed schema helper the app uses for queries," and clarifies dialect handling (kysely, drizzle, snake_case kysely). This clearly distinguishes it from siblings like execute_sql and query_database.

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 names the alternative and the condition that selects it: "Usually NOT needed after execute_sql — schema-changing statements re-pull automatically. Use it to refresh manually, or with helper_name..." It provides both when-to-use and 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?

Annotations already cover the safety profile (readOnlyHint, destructiveHint=false, openWorldHint), but the description adds genuinely new behavioral detail: write rejection, and the exact return shape including the truncated indicator and multi-statement results array. This is valuable because there is no output schema.

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

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

Three sentences, front-loaded with the action and read-only constraint, then routing guidance, then return shape. No filler; every sentence delivers information an agent needs to invoke 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?

For a read-only query tool with annotations covering safety and no output schema, the description fills the remaining gaps by documenting return structure and the write-rejection behavior. Nothing essential to 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 0%, so the description carries the burden. It meaningfully explains the non-obvious 'database' parameter's conditional use, while 'query' and 'projectId' are self-evident from name and surrounding context. No syntax guidance for query is given, but the description's framing implies SQL.

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 (Run) and resource (READ-ONLY SQL query against Postgres), names the accepted statement classes (SELECT, EXPLAIN, etc.), and clarifies both database scopes (Floot-managed vs. external Postgres). It explicitly differentiates itself from the sibling execute_sql for write 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?

Provides an explicit when-not with a routing alternative: 'Writes are rejected — use execute_sql for those.' It also gives conditional guidance for the database parameter ('Pass database only if the project has more than one'), removing the main ambiguity an agent would face.

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 only declare readOnly=false, destructive=false, openWorld=true; the description goes far beyond by disclosing that the call completes only when the user finishes the connect flow, never expires, returns env var names but never secret values, re-calling returns the same pending request, and that already-connected credentials short-circuit without a dialog. It also warns never to ask the user to paste a secret and how to reopen a dialog via `instructions`.

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?

Nearly every sentence conveys real, load-bearing information, but the entire description is one enormous run-on paragraph with deeply nested parentheticals, making it hard to scan and front-load. Structure is the weak point: it would benefit from paragraph breaks or ordering, but the density is justified by the tool's 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 complex mutation tool with no output schema, the description covers completion behavior, return shape (env var names, not values), reuse/dedup behavior, non-blocking workflow guidance, and error/refusal conditions. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 67% and the `type` enum carries no schema description, yet the description supplies the critical semantics: POSTGRES is mandatory for Postgres credentials (GENERIC is refused), GENERIC requires secret_env_vars, and later-producible vars belong in optional_env_vars. It explains why secret_env_vars has no default and how names drive reuse matching, adding substantial meaning beyond the schema text.

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

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

The description opens with a precise verb+resource ('Request the USER'S OWN external credential for this project') and immediately enumerates the concrete credential kinds it handles (OpenAI/Anthropic keys, Postgres connection strings, generic service keys). It also explicitly contrasts itself with the sibling 'provision_resource', so an agent can distinguish the two 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?

It states when to use this tool, when NOT to ('NOT for Floot-managed resources ... use provision_resource for those'), and a clear reuse-first ordering with the fallback connect-link path. The condition selecting each type (POSTGRES vs GENERIC, GENERIC requiring secret_env_vars) is spelled out, leaving almost nothing to inference.

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 openWorldHint=true, so the mutation surface is flagged. The description adds real value beyond that: the fails-fast-on-disconnected-browser behavior, the cross-origin iframe constraint, and the returned-string contract. Minor gap: it doesn't state that arbitrary code execution can mutate app state through clicks, though 'destructiveHint' covers the safety profile.

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 content is dense and useful, but the description is long-winded with parenthetical asides ('(unlike run_code_in_vm, which is a plain script returning stdout)'). Front-loading is good, but some sentences could be tightened.

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

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

No output schema, so the returned-string contract must be stated — and it is. No annotations cover the iframe/editor context, and the description covers it thoroughly. Remaining gap is the undocumented projectId, which matters for 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 coverage is 50%, with projectId undocumented in the schema. The description compensates by clarifying the code parameter's contract (module exporting a default async function, returns a string, runs at project root, imports by relative path), though projectId itself remains 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?

States a specific verb and execution context ('Run a TypeScript snippet inside the RUNNING APP's preview document'), and explicitly disambiguates from the sibling run_code_in_vm. An agent knows exactly what this does and how it differs.

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/when-not routing: 'prefer run_code_in_vm for anything that doesn't need the DOM', names simple interaction checks as good fits, and calls out multi-step e2e journeys and typed input as cases to leave to the user. This is exemplary 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 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, so the read-only nature is covered. The description adds valuable behavioral context: default capture uses the user's current device, and passing viewport temporarily switches the preview only for the capture. This prevents an agent from assuming the device change is persistent. It doesn't mention response format, but that is not central to behavioral safety.

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 deliver purpose, usage timing, default behavior, device-switching semantics, and a guardrail against an anti-pattern. Everything is front-loaded and substantive; there is no filler or redundant restatement of the title or annotations.

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 provides enough context for an agent to decide when to call the tool, what projectId to supply, and how to use viewport correctly. The only minor gap is not describing what the tool returns (e.g., an image path or data), but for a screenshot capture this is largely inferable.

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 viewport parameter is richly documented with concrete presets, pixel dimensions, a custom WIDTHxHEIGHT format, and a recommended default for phone checks. The description body reinforces the default behavior when viewport is omitted. projectId is straightforward as the required project identifier, so the 50% schema coverage is adequately compensated.

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: 'Capture a screenshot of the user app.' It also clarifies why to call it — to see layout, styling, or rendered state, or to debug — which distinguishes it from sibling tools that navigate or return URLs. The anti-pattern warning about building a separate mobile page further sharpens its unique 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?

The description explicitly says to call it whenever the agent wants to see the current app state, and it gives concrete guidance for the viewport parameter, including that the preview switches only for capture and then back. It does not explicitly compare against sibling read-only tools like get_preview_url or navigate_preview, but the context is strong enough to guide 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?

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 and readOnlyHint=false, but the description adds value beyond them: the subdomain is released, and the agent is told to require user confirmation before acting. It doesn't cover reversibility or post-unpublish state, which keeps it from a 5.

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

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

Two tightly written sentences, front-loaded with the action and the destructive warning, with a pointer to a guide at the end. No wasted words.

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

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

For a one-parameter destructive tool with no output schema, the description covers purpose, destructiveness, confirmation, and a guide pointer. The only real gap is the undocumented projectId parameter.

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 single required parameter 'projectId' is undocumented in both schema and description. The description says nothing about which project identifier is expected, so it fails to compensate for the coverage gap.

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

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

States a precise verb+resource ('take the published app offline') and even names the side effect ('release its subdomain'). This clearly distinguishes it from the sibling publish_app.

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: take the live app offline. It adds an operational precondition ('confirm with the user first') and routes the agent to get_guides('publishing') for detail. It does not explicitly name publish_app as the reverse alternative, so it falls short of full when/when-not coverage.

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 say readOnlyHint=false/destructiveHint=false; the description discloses far more: changes apply on next publish not now, invalid keys are reported and skipped, iosDeviceFamily is a one-way door that can fail at App Store upload, securityHeaders changes that would break the app are refused, and several settings require coordinated app-code changes. This is rich behavioral context beyond the annotations.

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

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

The purpose is front-loaded and every topic is relevant, but the description is a single unbroken wall of text and re-explains several settings (analyticsMode, serverMemoryMb, iosDeviceFamily, securityHeaders) that the schema already documents in detail, so a meaningful share of the length is redundant. Given the genuine complexity of an 8-parameter tool, the size is defensible but the structure is not.

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

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

For a complex, high-risk mutation tool with no output schema, the description covers deploy timing, prerequisites (get_guides), failure modes, null/reset semantics and cross-file caveats, so an agent has everything needed to invoke it safely. No return-value documentation is required since there is no output schema.

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

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

Schema coverage is already 88%, but the generic `updates` flat object carries no per-key meaning on its own, and the description supplies it: title length bounds, iconUrl/splashUrl accepted value forms, null-to-reset semantics, boolean key behavior, and the full shape/meaning of shareTarget, nativeSystemBars, securityHeaders and analyticsMode beyond the schema text.

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

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

States a specific verb and resource ('Update project settings') and then enumerates the exact keys that can be changed, with a pointer to where current values live (list_files). It distinguishes itself from siblings by referencing publish_app, write_file/edit_file, upload_asset, generate_image and request_user_upload for adjacent tasks.

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/when-not rules for the risky settings: 'EXPERT SETTING — NEVER change it on your own initiative', 'Only change it when the user asks about analytics, cookies, consent or privacy', 'Change it only when the user asks about embedding / iframes'. It also routes the agent to alternatives (edit static/__dev/native/*.plist directly after first publish, read get_guides first) so the agent knows when another tool is correct.

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

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

Annotations only declare readOnlyHint=false, destructiveHint=false, openWorldHint=true. The description adds substantial behavior the annotations cannot convey: three distinct upload modes with different completion semantics (inline vs presigned), size caps (3 MB inline, 100 MB presigned), short-lived uploadUrl, and the S3 egress-block failure signature (missing x-amz-request-id header) plus the explicit 'do not retry, switch paths' guidance.

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

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

Front-loaded on the core verb and the critical disqualifier (chat attachments), then structured by mode. It is long, but given six parameters, three modes, and a hard failure mode, nearly every sentence carries operative information. A tighter edit could fold the failure-path list, but nothing is pure filler.

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

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

No output schema exists, and the description names the return values (publicUrl, uploadUrl) and the full call lifecycle for each mode. For a 6-parameter tool with nested objects and out-of-band PUT steps, all the information needed to invoke it correctly on the first attempt is present.

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

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

Schema coverage is 67% and the description compensates well, explaining that file_id/download_url are host-issued and cannot be hand-constructed, that size_bytes must equal the decoded length in base64 mode and the exact PUT byte count otherwise, and that content_type is a derived hint in file mode. It does not restate the file_name pattern, but the schema covers that.

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

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

States a specific verb and resource ('Upload a binary asset ... to the project's hosted storage') and immediately delimits scope against siblings: request_user_upload for chat attachments, generate_image for fresh AI imagery. An agent can distinguish it from card_upload_asset, copy_file, and write_file without opening any schema.

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

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

Explicitly routes between four alternatives with the selecting condition for each: request_user_upload when the bytes are user-provided, generate_image when generating fresh imagery, the `file` param for ChatGPT conversation files, and run_code_in_vm PUT when sandbox egress is blocked. It also states the when-not case (chat attachments never reach MCP servers) with the reason.

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.