Fastero

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

Beyond the annotations (destructive=true, idempotent=true), it discloses concrete effects: the emailed link stops working, pending invites are never sent, and nothing is emailed either way. It also names the 400 refusal case for already-accepted/cancelled invites and states the return shape, which the annotations alone 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-loads the core action and effect, then prerequisites and error behavior. Three compact sentences, each carrying distinct information with no 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?

There is no output schema, but the description supplies the return value ({ message: 'Invite cancelled' }), the side effects, the auth requirement, and the failure mode. For a two-parameter destructive tool, an agent has everything needed to call it correctly.

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

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

Schema description coverage is 100%, so both parameters are already documented, including the inviteId source (_id from list_project_invites or the inviteId from invite_to_project). The description adds only marginal framing about which invite states are eligible; baseline 3 applies when the schema does the heavy lifting.

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 ('Cancel') and resource ('project invite'), and immediately disambiguates the two invite states (emailed link vs. awaiting confirmation). This clearly separates it from fastero_invite_to_project and fastero_list_project_invites.

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 gives the use case ('withdraw an invite to a wrong or unwanted address') and the hard exclusion ('it cannot remove someone who has already accepted'). It also adds necessary prerequisites ('Owner or Admin role') and the refused-state condition (already accepted/cancelled returns 400), leaving 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 only say readOnlyHint=false and destructiveHint=true; the description adds rich behavior beyond that: emails on crossing, again on return, once if the check starts failing, silence while staying across the line, org-member recipient constraint, default-to-self, at-most-hourly cadence, and upsert-on-repeat (which explains the destructive overwrite hint). This is exactly the extra context annotations cannot carry.

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?

Dense but every clause is load-bearing — purpose is front-loaded, then semantics, recipients, cadence, upsert, and the disable sibling. No filler or repetition.

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

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

With no output schema, the description fully carries the burden: it explains trigger conditions, email behavior, recipient rules, cadence limits, and update behavior. An agent can call it correctly without further inference.

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 63%, and the description compensates meaningfully: it defines the column fallback ('first numeric column when none is named'), the op comparison set, the default recipient behavior, and cadence/timezone reading. projectId and queryId are left to their schema descriptions, so not a full 5.

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

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

States a specific verb+resource and scope: 'Watch one number from a saved query and email when it crosses a line.' It clearly separates itself from sibling creation tools (create_query, create_report, create_dashboard) by naming the alerting/threshold 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?

Gives clear usage context — it executes a saved query on each run, and 'The same query and condition asked again updates the timetable and recipients' defines upsert semantics. It also names the alternative fastero_set_schedule_enabled for switching off. No explicit when-not-to-use beyond that, so a 4 rather than 5.

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

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

Annotations only cover the readOnly/destructive profile, and the description carries the rest itself: credentials pass through the model and persist in plain text in the session transcript, the connection is tested before saving so unreachable databases are not persisted, refusal messages name a cause, and permission is limited to owners/admins/editors. The only shortfall is that the SSH host-key refusal flow is described at length while nothing is said about other failure modes such as duplicate names or credential rotation.

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 purpose, then exclusions, then the failure/test-before-save behaviour, then SSH, then the return value and permissions — a sensible order. It is a dense single block of roughly 250 words with the SSH edge case consuming nearly a third of it; readable but the wall-of-text format costs it a point.

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, so the description supplies the return contract itself ('the new connection's _id, the connectionId other tools take'). Combined with the mutation side effects, prerequisite tools, permission scope and error semantics, an agent has everything needed to invoke this correctly on the first try.

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 100%, so a 3 would be the floor, but the description goes well beyond it: it documents the nested creds fields for bastion access (sshHost, sshPort with its default of 22, sshUsername, sshKeyId, sshHostKey), redefines what `host` means when a bastion is used (and that Oracle takes an IP address there), and explicitly neutralises projectId as not needed. That is real semantic value the schema does not supply.

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

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

States a specific verb and resource ('Create a data connection to a database'), enumerates the supported datasources, and immediately distinguishes itself from the two nearest siblings: OAuth sources (BigQuery, Google Sheets) that need a browser sign-in, and fastero_create_file_connection for uploaded CSV/Excel files. An agent can route correctly 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?

Explicit when-to-use with the caveat that the web app is the preferred route because credentials land in the transcript, explicit when-not (OAuth sources, file uploads), and an explicit prerequisite chain for SSH (sshKeyId from fastero_create_ssh_key, host-key fingerprint verification). Exclusions and alternatives are both named.

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: it discloses the organization-wide sharing side effect, that names are non-unique, the returned payload (_id and url), and the plan-limit failure mode with its error message. That is exactly the mutation-consequence context annotations alone (readOnlyHint=false, destructiveHint=false) 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?

Four sentences, front-loaded with the action and scope, then workflow, then return value, then failure mode. Each sentence earns its place, though the workflow sentence is densely packed and could be split for scanning.

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

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

With no output schema, the description supplies the return shape itself, and for a mutating create tool it covers side effects, naming rules, follow-up tools, and the quota failure. An agent has everything needed to call it and interpret the result.

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

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

Schema coverage is 100%, so the three parameters are already documented, including projectId's source. The description adds one genuinely new constraint, that two dashboards may share a name, but nothing about the optional description field or format expectations. Baseline 3 fits.

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

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

States a specific verb and resource ('Create an empty dashboard in a project') plus the scope of who sees it. The word 'empty' plus the pointer to fastero_save_chart / fastero_update_dashboard for populating it separates this cleanly from fastero_create_report, fastero_create_page and the other create_* 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?

Explains the workflow: create empty here, then add charts via fastero_save_chart or place existing reports via fastero_update_dashboard. It gives clear context for when this tool is the right entry point but does not state explicit exclusions or say when to prefer creating a report instead.

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 non-readOnly, non-destructive annotations, the description discloses return values (connectionId, tableName), idempotency behavior (existing connection returns created: false unless sheetName differs), latest-upload read semantics, Excel sheet defaulting, file-type restrictions, and required project roles.

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 core action and then layers in return values, workflow siblings, edge cases, and permissions. Every sentence carries operational information; there is no filler.

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

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

Although there is no output schema, the description explains what the tool returns (connectionId and tableName), the idempotent created: false case, downstream querying, file-type refusal, Excel sheet selection, and permission requirements. That is enough for an agent to call it correctly without opening sibling schemas.

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

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

Schema coverage is 100%, so baseline is 3. The description adds context for sheetName by explaining that an Excel file yields one sheet and that an existing connection is returned unless sheetName requests a sheet it does not hold, which is behavioral meaning not present in the schema.

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

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

The description opens with a specific verb and resource: it creates a SQL queryable connection over an uploaded CSV or Excel file, holding it as one table. It explicitly distinguishes this from fastero_create_connection, which is for databases, and names the sibling tools used on the resulting connection.

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 (uploaded CSV/Excel files), when not to use it (any other file type is refused; databases use fastero_create_connection instead), and how to proceed afterward with fastero_run_sql, fastero_list_connection_schemas, fastero_create_query, and fastero_save_chart.

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 behavior beyond the annotations: the created notebook is empty (no cells), duplicate titles are allowed ('Two notebooks may share a title'), and it returns the notebook including its _id. Annotations already cover the mutation/safety profile, so the remaining gap is only around permissions or project-existence requirements.

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

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

Front-loads the action and the empty-notebook constraint, then routes to alternatives. The mid-sentence explanation of what a notebook is ('Python and SQL code cells and markdown, run top to bottom in a fresh kernel…') is definitional padding that a shorter clause could cover, though it does aid disambiguation.

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?

Three params, full schema coverage, and the description supplies the return shape ('the notebook with its _id') even without an output schema, plus sibling routing. Only error/precondition behavior (e.g., what happens with an invalid projectId) is left unstated, which is a minor 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 coverage is 100%, so the schema already documents name, projectId, and description; baseline is 3. The description adds one semantic fact about the name parameter (titles are not unique), but says nothing extra about projectId sourcing or the optional 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?

Opens with a precise verb+resource+state: 'Create an empty notebook in a project, with no cells,' and immediately clarifies the resource is populated by fastero_write_notebook. An agent can distinguish it from write_notebook and from the project/app creation siblings without opening a 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 explicit routing: use fastero_write_notebook to add cells, fastero_create_python_project for script-style .py jobs with logs, fastero_create_streamlit_app for browser apps. Both the when-to-use-this and the when-to-use-a-sibling conditions are stated.

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

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

Goes well past the annotations (readOnlyHint=false, destructiveHint=false): it documents the sandbox contract (CDN allowlist of cdnjs.cloudflare.com and cdn.jsdelivr.net, all other fetches/XHR blocked), the in-page runtime API (fastero.data, fastero.onRefresh, fastero.open), and the return value ('the page without its HTML, with url'). That is substantial behavioral context an agent cannot get from 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?

Purpose and return value are front-loaded and the paragraph is dense with non-redundant detail. A few clauses (the min-width: 0 / tile-wrapping layout tip, the open({dashboard}) aside) sit closer to authoring advice than tool selection, so it is busy but not padded.

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

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

No output schema exists, and the description compensates by stating what is returned (page object without HTML, plus url) and how to surface it (fastero_show_page). With 5 parameters and thin annotations, the remaining gap is edit/overwrite and failure behavior — e.g., what happens if the name already exists or when the excluded 'integration' widget type is supplied (the latter is only covered in the schema).

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

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

Schema coverage is 100%, so baseline is 3, and the description earns an extra point by explaining the coupling between the `widgets` parameter and page code — `<name>` in `fastero.data("<name>")` must match a name given in widgets. The layout advice ('fit from about 600px wide... give flex items that hold charts min-width: 0') also adds meaning about expected HTML content beyond the 2 MB limit in 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?

Opens with a specific verb and resource: 'Publish an HTML dashboard page to a project,' then defines what a page is ('one HTML document that runs sealed off in a member's browser'), which separates it from fastero_create_dashboard and fastero_create_streamlit_app without naming them. An agent knows exactly what artifact this produces.

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

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

Usage is implied rather than stated: it asserts the page should 'read the numbers rather than writing them into the page' and points to fastero_show_page for displaying the result. It never says when to choose a page over a dashboard, streamlit app, or report, nor what prerequisites or naming/overwrite behavior apply, so the agent must infer tool 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 only declare readOnlyHint=false/destructiveHint=false; the description goes well beyond by disclosing exactly what gets created 'local' (main.py, .env.sample, README.md, an entrypoint 'main') versus 'git' (no entrypoint, repo read on listing or first run). It flags the private-repo auth prerequisite, notes duplicate names are allowed, and states the return value ('the project with its _id').

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 and scope are front-loaded in the first sentence, and the closing sentence routes to siblings. Some phrasing is dense and meandering (the nested private-repository clause, 'each run as a script on a machine of its own'), and a few details are marginal, but no sentence 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?

For a create tool with no output schema, the description covers the important ground: creation side effects, sourceType behavior, entrypoint lifecycle (fastero_ensure_python_entrypoint fills the gap for git-linked projects), auth prerequisites, and the returned identifier. 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 100%, so the schema already documents all five parameters, making 3 the baseline. The description adds real semantics beyond the schema, though: it states 'local' is the default, what the git object's values trigger (repo read on file listing or first run), and the entrypoint consequences of each sourceType. The remaining parameters (name, description, projectId) get no extra treatment, so it is not a 5.

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

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

Names a specific verb and resource ('Create a Python project') and immediately defines what that resource is: a workspace of .py files with entrypoints, run on its own machine, manually or scheduled. It explicitly distinguishes itself from the sibling creation tools (fastero_create_notebook for in-place analysis, fastero_create_streamlit_app for browser apps) so an agent can route without opening a 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 concrete fit criteria ('suits repeatable jobs and report generators') plus explicit alternatives with their selection conditions. It also states a hard exclusion: private git repositories require provider/token setup in the Fastero app, so such projects cannot be created through this tool in that case.

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 write shape (readOnlyHint=false, destructiveHint=false); the description adds real behavioral context: the SQL is persisted not executed, it must be read-only or the call is rejected, and duplicate names are permitted. It also describes the return value (_id/queryId), which matters since there is no output schema. Slightly short of 5 as it omits error/permission behavior beyond the read-only check.

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

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

Purpose is front-loaded in the first sentence and the saved-not-run distinction follows immediately. The paragraph is dense and the closing definitions sentence is somewhat tangential, but every sentence carries usable routing or behavioral information, so little is wasted.

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

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

With no output schema, the description compensates by naming the returned _id/queryId and which siblings consume it. Validation rules, duplicate-name tolerance, and related tools are all covered, so an agent has enough to invoke it correctly.

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

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

Schema coverage is 100%, so a 3 baseline would suffice, but the description adds semantic value by explaining that definitionsUsed records which shared definitions and versions the query was built from and tying it to fastero_get_definitions. That goes beyond the schema's terse field descriptions.

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

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

States a specific verb and resource ("Save a new SQL query against a connection") plus the downstream purposes (scheduling, sharing, reports). Explicitly distinguishes itself from fastero_run_sql ("The SQL is saved, not run"), so an agent can pick it without opening a 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 when-to-use routing: use fastero_run_sql to execute, fastero_save_chart when you want the query and chart together, and references that fastero_create_report/create_alert consume the returned queryId. Also states a when-not: SQL that could change data is refused.

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

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

Beyond the annotations, the description discloses validation behavior (a chart or map without assignments is refused), return values (the report with _id and url), and placement behavior via fastero_update_dashboard. It also explains that text blocks read no query and that vegaLite charts have editing and history constraints.

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 core action and supported report types, then adds the key constraints and alternatives. Despite the tool's complexity, every sentence carries actionable information and there is no filler.

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

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

For a 21-parameter creation tool with no output schema, the description covers the essential call shape, validation rules, return value, and sibling alternatives. The detailed input schema supplies the remaining parameter-level detail, so the description is complete enough for correct selection and invocation.

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

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

Schema coverage is 95%, so most parameter meaning is already documented. The description still adds cross-parameter semantics: chart and map assignments are mandatory, vegaLite replaces chartType and assignments for unsupported charts, text uses the text field, and SQL column aliases become visible labels.

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: create a report, defined as a dashboard widget, from a saved query. It enumerates the supported report kinds (table, number, map, chart, text block) and distinguishes the tool from fastero_update_dashboard and fastero_save_chart.

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 conditions: charts and maps require assignments or are refused; when chartType cannot express the chart, use vegaLite instead of chartType and assignments; text blocks use chartType text and read no query. It also names fastero_update_dashboard for placement and fastero_save_chart for the one-call SQL-to-dashboard path.

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

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

Beyond the annotations, the description discloses permission requirements ('Only organization owners and admins'), name-collision refusal, project-level override behavior, and the important security fact that the value is never returned by any tool and is kept in plain text in the client transcript. The annotations say readOnly=false and destructive=false, which the description is consistent with: this creates a new secret rather than reading or destructively modifying existing data.

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

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

The description is dense but front-loaded: it defines the resource first, then scoping, then collision/alternative behavior, then permission and return semantics. Every sentence carries operational or safety information, though the single long paragraph could be easier to scan if split.

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 three-parameter creation tool with no output schema, the description covers scope, override behavior, permissions, failure conditions, return shape, and the unusual value-handling/security caveat. An agent has enough information to decide whether to call this tool and what to expect.

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 100%, so the baseline is 3, but the description adds meaning beyond the schema: projectId omission scopes the secret to the whole organization, project-level secrets override same-named organization secrets, and duplicate names at the same level are refused. It also reinforces that value is write-only and never returned.

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

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

The description opens with a specific verb and resource ('Create a text Secret') and immediately defines what a Secret is and how it is consumed. It distinguishes creation from replacement by naming fastero_update_secret and mentions fastero_list_secrets as the way to find ids, so an agent can separate it from sibling tools.

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

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

It explicitly states the project-vs-organization scoping choice via projectId and the override rule. It also names the alternative for replacing an existing value (fastero_update_secret) and the discovery tool for ids (fastero_list_secrets), leaving little to infer.

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: it discloses that an Ed25519 key is generated per connection with the private half retained server-side, that keys are cached ('same key comes back until a connection uses it or a week has passed'), that authorizedKeysLine is only produced when host and port are supplied, and the permission model ('Owners, admins and editors'). readOnlyHint=false is consistent with key generation, so no contradiction.

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

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

The purpose and the sibling relationship are front-loaded in the first clause, followed by return values, caching behavior, and permissions in a logical order. Every sentence carries a distinct fact — no filler or restated title text.

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

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

There is no output schema, and the description fully compensates by naming all three returned fields and explaining when authorizedKeysLine appears. Combined with the caching window and role requirements, an agent has everything needed to call this correctly and to sequence it with fastero_create_connection.

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

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

Schema coverage is 100%, so baseline would be 3, but the description adds semantics the schema does not: host and port are optional and exist solely to fill in authorizedKeysLine, and are therefore unnecessary if the caller only needs the key. That is a real behavioral consequence of the parameter values, not a restatement.

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 ('Get the SSH key') scoped to 'a new connection to a database behind an SSH bastion (jump host)'. It also names the adjacent sibling (fastero_create_connection) and the condition that removes the need for this tool ('a database Fastero reaches directly needs none'), so an agent can distinguish it without opening a 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 explicit ordering ('before fastero_create_connection'), an explicit exclusion ('a database Fastero reaches directly needs none'), and the downstream handoff ('fastero_create_connection then takes the sshKeyId in creds'). When, when-not, and how it chains are all stated.

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

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

Annotations declare readOnlyHint=false and destructiveHint=false, so the write-but-non-destructive profile is already structured. The description adds real context beyond that: the app is created stopped, two apps may share a name, and owners/admins/editors are the roles that may create one. Return contents are described too.

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 what the tool creates, then behavior, then sibling routing; every sentence carries either a constraint or a routing decision. It is dense and long-ish for a single paragraph, but no sentence is 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 compensates by naming the returned fields (appId, status, viewerUrl, other settings, without files). Entrypoint constraints, permissions, and lifecycle are all covered, leaving nothing an agent needs missing.

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

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

Schema coverage is 100%, so the baseline is 3 and the schema already explains name, files, path and projectId. The description reinforces the app.py-at-top-level and requirements.txt constraints, but adds only one genuinely new semantic ('two apps may share a name') 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 and resource ('Create a Streamlit app in a project from the files given') and immediately defines the artifact as 'a Python web app that signed-in project members open in the browser', which separates it from notebooks and scheduled scripts. An agent can distinguish it from fastero_create_notebook and fastero_create_python_project without opening either schema.

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

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

Explicitly routes to alternatives by condition: fastero_write_streamlit_file to change one file, fastero_replace_streamlit_files to change all of them, fastero_create_notebook for in-place analysis, fastero_create_python_project for scheduled scripts. It also states the entry condition that fastero_run_streamlit_app (or a member opening the link) is what starts it, since creation leaves it stopped.

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 flag destructiveHint=true, but the description goes well beyond that by enumerating the cascade: saved queries keep SQL but lose the connection, dependent charts/dashboards/alerts break, and watching triggers are deleted. The closing clarification 'the database itself is not touched' is exactly the kind of scope boundary an agent needs before confirming a destructive call.

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 verb, resource and audience, then the impact. The second sentence is a long run-on chaining three separate consequences, which slightly hurts scannability, but no clause is filler.

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

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

For a single-parameter destructive tool with no output schema, the definition covers permission gating, downstream effects, trigger deletion, and the explicit non-effect on the database. Nothing needed to call it safely 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?

Only one parameter and schema coverage is 100%, with the schema itself explaining where the id comes from (fastero_list_connections, fastero_create_file_connection). The description adds nothing about connectionId, so baseline 3 applies.

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

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

States a specific verb and resource ('Delete a data connection') plus the blast radius ('for the whole organization'), which no sibling delete tool shares. An agent can immediately tell this apart from fastero_delete_query, fastero_delete_dashboard, or fastero_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?

Gives the permission precondition ('its owners, admins and editors can') and the consequences that inform a use/skip decision ('charts, dashboards and alerts ... stop until each query is moved'). It never names an explicit alternative or a 'do not use when' clause, so it falls short of a 5.

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

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

Goes well beyond the destructiveHint=true annotation by detailing the full consequence set: public link stops working, automatic refresh is switched off, and any email schedule disables itself at its next due time. It also clarifies what is NOT destroyed (charts and their saved queries survive, remaining in fastero_list_reports), which is exactly the kind of side-effect transparency a destructive tool needs.

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 well-formed sentences, front-loaded with the permanent/org-wide scope before the side effects and retention notes. The second sentence is dense but every clause (link, refresh, schedule, retention) earns its place. Slightly long but no filler.

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

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

For a destructive mutation with no output schema, the description is complete: it covers permanence, scope, downstream effects, and data retention. An agent has everything needed to warn the user and call it correctly.

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

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

Schema description coverage is 100% and both parameters (projectId, dashboardId) are documented with their source tools, so the schema carries the load. The description adds no syntax or format detail about the parameters themselves, making the baseline 3 appropriate.

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 (Delete) and resource (dashboard) and precisely scopes it as permanent and organization-wide ('not just you'), which separates it from the softer update_dashboard sibling. An agent can tell immediately what this does and its blast radius.

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 conveys the severity and permanence of the action, which implicitly signals when caution is warranted, but it never names an alternative tool or states explicit when-to-use/when-not conditions versus siblings like update_dashboard or delete_report. Usage is implied rather than spelled out.

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?

Far exceeds what the annotations declare. Beyond destructiveHint=true, it explains that contents are erased irrecoverably, that dependent dashboards retain their charts (rows stored locally) but lose Excel export/recalculation and assistant readability. This downstream-impact detail is exactly the behavioral context annotations cannot express.

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 core action is front-loaded in the first clause, and every subsequent clause (irreversibility, dashboard impact, assistant access) carries non-redundant information. No filler.

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

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

For a 2-parameter destructive mutation with no output schema, the description supplies the full consequence model: irreversibility, collateral impact on dashboards, and loss of programmatic access. Nothing an agent needs before calling it is missing.

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

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

Schema description coverage is 100% and both parameters already document their source tools (fastero_list_files, fastero_list_projects). The description adds no additional parameter-level meaning, so the baseline 3 applies.

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

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

States a specific verb (delete) and a precisely scoped resource (an uploaded project file, for everyone in the project). The resource 'file' is clearly distinct from the other delete siblings (dashboard, notebook, query, report, page), so an agent can disambiguate 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?

The description conveys the scope and seriousness of the operation but never states when to choose this over an alternative (e.g., rename_file) or any prerequisite such as confirming the file is unused. Usage is implied by the destructive wording rather than made explicit.

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

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

Annotations only declare destructiveHint=true; the description adds the material consequences: destruction is permanent, affects everyone in the project, and any schedule running the notebook disables itself the next time it comes due. That cascade behavior is exactly what an agent needs and is not in the annotations.

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

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

Three sentences, no filler: the destructive scope comes first, the schedule side effect second, and the alternatives last. Front-loading the permanence warning is the right ordering for a delete 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 destructive tool with full annotation coverage and a complete parameter schema, this covers what remains: irreversibility, blast radius, side effects on schedules, and escape hatches. No output schema exists but none is needed for a delete.

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?

Both parameters are fully documented in the schema (100% coverage), including where to obtain each id, so the description correctly leaves them alone. It adds no syntactic or format detail of its own, which is the expected baseline case.

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 (delete) and resource (notebook) with explicit scope: the output saved in it, permanently, for everyone in the project. It also names the two siblings an agent might confuse it with, so the tool is distinguishable without opening a 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 the agent to alternatives: fastero_set_schedule_enabled when the notebook should be kept but scheduled runs stopped, and fastero_write_notebook when cells should be replaced. Both the when-to-use and the when-to-use-instead are stated.

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

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

Annotations only declare destructiveHint=true and readOnlyHint=false; the description goes well beyond by disclosing the exact blast radius: the link 404s for everyone in the project, auto-refresh stops, and widgets/queries/spreadsheets are preserved. It also states the returned _id, which matters since no output schema exists.

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 action, then cascade effects, then the non-destructive alternative, then the return value. Every sentence carries distinct information and none is wasted despite the four-sentence 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 two-parameter destructive tool with no output schema, the definition covers action, side effects, preserved resources, the alternative path, and the return value. Nothing an agent needs to call it safely is missing.

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

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

Schema description coverage is 100%, so the origin of both pageId and projectId is already documented in the schema. The description adds no format, constraint, or scoping detail beyond what the properties already say, so the baseline 3 applies.

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

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

Starts with a specific verb+resource ('Delete a hosted page') and immediately disambiguates from the sibling 'fastero_delete_dashboard' by noting a dashboard deletion cascades to its page. An agent can distinguish this from get_page, update_page, delete_dashboard 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 the agent: use fastero_delete_dashboard when the goal is the dashboard, and use fastero_update_page when the goal is to change content while preserving the link. The when-not condition (don't use this to edit) is stated outright.

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 flag destructiveHint=true, yet the description goes well beyond that by enumerating exact consequences: the project leaves fastero_list_python_projects, schedules are switched off, it can no longer be run/scheduled/written to. It also clearly separates irreversibly erased stored files from preserved run history, which is precisely the kind of detail an agent needs for a destructive call.

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

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

Two sentences, front-loaded with the action and scope, then the consequences in a single dense clause. No filler or repetition of the title.

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

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

For a destructive two-parameter tool with no output schema, everything needed to call it safely is present: scope, listed consequences, what is retained versus destroyed, and unrecoverability. No relevant gap remains.

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

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

Schema description coverage is 100% and both parameters already document their source (fastero_list_projects, fastero_list_python_projects). The description adds no additional meaning about the identifiers, so the baseline 3 applies.

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

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

States a specific verb and resource ("Delete a Python project") plus the blast radius ("for everyone in the project"), which is far stronger than the bare title. It doesn't explicitly contrast with sibling delete tools (delete_notebook, delete_streamlit_app), but the resource naming makes selection unambiguous.

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

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

Usage is implied by the operation type, but there is no explicit when/when-not guidance, e.g., that disabling schedules or triggers (set_schedule_enabled / disable_trigger) is the non-destructive alternative, or that a project that must remain runnable should not be deleted. The agent must infer the trade-off.

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 destructiveHint=true annotation by disclosing irreversibility ('cannot be restored here'), scope (affects everyone in the project), and downstream cascade effects: dependent reports stay but render nothing and are marked unavailable, and dependent alerts self-disable at their next check. This is exactly the behavioral context an agent needs before a destructive call.

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 irreversibility in the first clause, then adds consequences. Slightly dense in the second half (reports + alerts + cross-reference), but nearly every clause carries decision-relevant 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 two-parameter mutation with annotations present and no output schema, the definition covers scope, irreversibility, and side effects on reports and alerts, plus where to inspect dependents. Nothing essential to calling it safely is missing.

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

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

Schema description coverage is 100%, so both parameters (queryId, projectId) and their provenance are already documented in the schema. The description adds no additional meaning about parameter format or constraints, so the baseline 3 applies.

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

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

Specific verb (delete) plus resource (saved query) and explicit scope ('for everyone in the project'), which separates it from other delete siblings on dashboards, notebooks, pages, etc. An agent can distinguish it from fastero_update_query and fastero_get_query 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?

Clear context for when to call it and it routes the agent to fastero_list_reports to inspect dependents (and the schema points to fastero_list_queries for the id). It does not state an explicit when-not or a true alternative for removing a query, but the surrounding guidance is solid.

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 goes well beyond that by disclosing exactly what is destroyed and what is preserved: dashboards keep their other charts and the underlying saved query is retained. That is precisely the context an agent needs before committing an irreversible mutation.

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

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

Three tight sentences, each earning its place: the core action, the preservation semantics, and the alternative route. The destructive scope is front-loaded ahead of the sibling pointers.

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 is needed for a delete, and the description covers the safety profile, blast radius, and alternatives. Nothing required to call this tool correctly is missing.

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

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

Schema description coverage is 100% and both parameters are documented with their sources (fastero_list_reports, fastero_get_dashboard, fastero_list_projects). The description adds no further parameter meaning, so the baseline 3 applies.

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

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

States a specific verb and resource ('Delete a report permanently') and immediately scopes the blast radius (comes off every dashboard in the organization). It names two related siblings, fastero_delete_query and fastero_update_dashboard, so an agent can distinguish it from adjacent operations without opening schemas.

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

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

Explicitly covers when to use it (permanent org-wide removal), what it does not do (the saved query survives), and the alternative path for a narrower intent ('To take it off one dashboard only, fastero_update_dashboard with a layout that leaves it out'). The routing decision is fully specified.

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 destructiveHint=true; the description adds concrete consequences: removal from listings, server stopped, address no longer resolves, and deletion of saved packages, the Git token, and repository-fetched files. It also states irreversibility and project-wide blast radius, which an agent needs before calling a destructive tool.

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

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

A single sentence that front-loads the action and scope, then enumerates consequences in a scannable clause chain. No filler or restatement of the title.

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

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

For a two-parameter destructive tool with no output schema, the definition covers action, scope, side effects, irreversibility, and parameter provenance. Nothing an agent needs in order to call it correctly is missing.

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

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

Schema coverage is 100% and both parameters (appId, projectId) are documented with provenance in the schema itself. The description adds no format, constraint, or validation detail beyond that, so the baseline 3 applies.

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

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

States a specific verb (Delete) and resource (Streamlit app) plus an explicit scope qualifier: 'for everyone in the project'. That scope statement distinguishes it from narrower per-user or file-level operations among the many fastero_delete_* 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?

Implicitly routes the agent by naming fastero_list_streamlit_apps as the source of the appId and by warning 'It cannot be restored here', which signals this is not a reversible or soft operation. It stops short of naming an alternative (e.g. replace_streamlit_files) when the user only wants to change content.

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 write/idempotent/non-destructive at a generic level; the description adds concrete behavior—running jobs finish, the trigger is retained (not deleted) for re-enabling, and an already-off trigger is refused with no change. This is exactly the extra context the bar asks for, and nothing contradicts idempotentHint=true or destructiveHint=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?

Purpose is front-loaded in the first clause, and every subsequent sentence carries distinct information (persistence, permissions, edge case, alternative). It is dense and somewhat run-on, but there is no filler to cut.

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, but the description fully covers what an agent needs to call it correctly: side effects, reversibility, authorization, refusal behavior, and the alternative tool for adjacent trigger types.

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?

Single parameter with 100% schema coverage; the schema already documents triggerId and even its source (fastero_list_triggers). The description adds no syntax or format detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb+resource (pause a trigger) and immediately enumerates what it affects across the domain: Python schedules, dashboard/page refresh, watchers. It explicitly names the re-enabling sibling fastero_enable_trigger, so an agent can differentiate 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?

Gives explicit conditions: use fastero_enable_trigger to reverse, and use fastero_set_schedule_enabled instead for dashboard emails, alerts and notebook runs. Also states permission scope (owners, admins, editors can pause any trigger) and the already-disabled edge case.

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

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

Beyond the annotations (readOnlyHint=false, idempotentHint=true, destructiveHint=false), the description adds that nothing runs immediately, that permission is required, and that an already-enabled trigger is refused as a no-op. The refusal semantics are a meaningful nuance on top of the idempotency hint.

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 effect ('switch back on' plus what that means), then constraints and the alternative. Every sentence carries distinct information with no 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 single-parameter toggle with no output schema and safety already covered by annotations, the description supplies effects, permissions, no-op behavior, and sibling routing. Nothing an agent needs to call it correctly is missing.

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

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

Only one parameter (triggerId) and schema description coverage is 100%, so the schema already documents it, including its provenance ('from fastero_list_triggers'). The description adds nothing further about the parameter, so the baseline 3 applies.

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

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

States a specific verb+resource ('Switch a trigger back on') and enumerates what a trigger covers (Python schedule, dashboard/page refresh, watcher), which lets an agent identify the resource class precisely. It also explicitly excludes dashboard emails, alerts and notebook runs, routing those to a named sibling.

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

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

Gives explicit conditions: who may use it (owners, admins, editors of the org, regardless of creator), what happens if the trigger is already on (refused, nothing changes), and names the alternative (fastero_set_schedule_enabled) for non-trigger schedules. No inference required.

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 idempotentHint annotation by explaining why re-calling is safe and warning that schedules are keyed to the entrypoint id, which is non-obvious and prevents accidental duplication. It does not disclose permission requirements or behavior when the path is absent/invalid.

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

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

Three tight sentences, front-loaded with the primary action and each carrying distinct information (what it does, the file-type constraint, idempotency rationale). No filler.

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

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

With no output schema, the description usefully states the return value (an entrypoint id) and the idempotency contract. For a simple 3-param tool with annotations covering safety, this is nearly complete; only error/permission behavior is unaddressed.

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

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

Schema description coverage is 100%, so projectId and pythonProjectId are already documented. The '.py only' constraint overlaps the schema's own 'Path of the .py file' wording, adding little beyond what the schema already states; baseline 3 applies.

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

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

States a specific verb+resource: turns a Python file into an entrypoint and returns the entrypoint id. The operation is distinct from every sibling (no other tool touches entrypoints), and the '.py only' scope is stated up front.

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 ('make a file runnable') plus a real precondition/exclusion ('Only a .py file can be an entrypoint') and re-call guidance ('Safe to call again'). It does not name alternative tools (e.g. write_python_file) for adjacent tasks, so it stops short of a 5.

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

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

Annotations only declare a safe read; the description goes well beyond by disclosing the returned field set (name, datasource, non-secret credentials, connectionTest timestamps and message, sshAuthorizedKeysLine), the redaction guarantee ('Passwords, private and secret keys, and tokens never come back'), and the authorization scope ('Any member of the organisation can read it'). That is exactly the context annotations cannot carry.

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, front-loaded with the purpose, then fields, then alternatives. The mid-sentence field enumeration is heavy but every element (secret redaction, SSH bastion case, failure message, auth scope) earns its place; a light restructuring into sentences would read better.

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

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

There is no output schema, so the description must describe the return shape, and it does so field by field, including the conditional SSH field and the test-status subfields. With permissions, redaction and not-found behaviour all covered, nothing an agent needs before calling is missing.

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

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

Schema coverage is 100% and the single connectionId parameter is already documented in the schema as coming from fastero_list_connections. The description adds only the behavioural consequence of an unknown id, not new syntax or format semantics, so baseline 3 applies.

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

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

Opens with a specific verb and resource ('Read one data connection's settings') and immediately enumerates what those settings are. It explicitly distinguishes itself from fastero_list_connections (id + list, no details) and fastero_list_connection_schemas (tables), so an agent can route between the three 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?

'Use it to see where a connection points or why it fails' states the selecting condition, and both alternative siblings are named with what they return instead. It even names the substitute result for a bad id ('Connection not found'), removing ambiguity about failure semantics.

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; the description goes further by stating "Nothing is run", disclosing the authorization profile ("Any project member, viewers included, can read it") and the failure mode ("A dashboard not in this project answers 'Dashboard not found'"). It also clarifies the ambiguous null semantics of refresh (none vs. paused) and where a paused trigger is discoverable.

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 highest-value content (what it returns, and the read-before-update rule) is front-loaded with no filler sentences. The closing trigger paragraph is convoluted — it packs disable/enable/list_triggers and the dashboard:<id> naming convention into one dense run of clauses that takes a second pass to parse.

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

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

There is no output schema, so the description carries the entire burden of explaining return values, and it does so field by field, including the distinction between item placement (reportId) and chart content. Permissions, error behavior, and mutation-adjacency are all covered for a two-parameter read tool.

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

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

Schema description coverage is 100% and both parameters already state their provenance (projectId from fastero_list_projects, dashboardId from fastero_list_dashboards), so the schema does the heavy lifting. The description adds no format, casing, or ID-shape detail beyond that, leaving this at the baseline.

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

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

Opens with a specific verb+resource ("Read one dashboard's layout and settings") and then enumerates exactly what is returned: name, description, filters, tabs, items, url, refresh. It also draws the line against the two nearest siblings (fastero_list_dashboards omits url and refresh; fastero_get_report covers what a chart shows), so an agent can route without opening either schema.

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

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

Gives an explicit ordering rule ("Read it before fastero_update_dashboard, whose layout, filters and tabs each replace the whole list") and names the alternatives for adjacent needs: fastero_get_report for chart content, fastero_list_dashboards for a cheap list, fastero_disable_trigger/enable_trigger plus fastero_list_triggers for paused refresh. Each alternative is paired with the condition that selects 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?

Beyond readOnlyHint/destructiveHint, it discloses permission requirements, that deleted or out-of-project dashboards return not found, and that the link is openable without signing in. It also spells out the three possible states and what each implies (never shared, revoked, expired), which 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?

Purpose and the sibling distinction are front-loaded, and the return-state enumeration is dense but earned. It is a single long paragraph, however, and the state/return details could have been split for faster scanning by an agent.

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

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

There is no output schema, so the description carries the full burden of explaining returns, and it does so completely: status values, shareUrl/confirmUrl, expiresAt, and the live refresh descriptor. Nothing needed to interpret the response is missing.

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

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

Schema coverage is 100%, so both parameters are already documented with their source tools. The description adds domain meaning by noting that a dashboard outside the project yields not found, which clarifies the relational constraint between projectId and dashboardId. It does not add format or id-shape detail beyond the schema, so it sits just above baseline.

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

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

It states a specific verb-and-resource pair ('Read whether a dashboard has a public link, and its state') and explicitly disclaims the mutation sibling: 'fastero_share_dashboard is the tool that asks for a link or refreshes one.' The agent can distinguish it from every other dashboard sibling, including fastero_get_dashboard, without opening a 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 names both use cases ('find a dashboard's public address' or 'learn whether a link asked for is still awaiting confirmation') and names the alternative tool that performs the write. It also states the eligibility condition (Owner, Admin or Editor role) and the not-found condition, so the agent knows when this call is appropriate and when it will fail.

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 safety is covered. The description adds real behavioral context beyond that: connectionId returns organisation-wide definitions plus the connection's own, with the connection's own replacing an org-wide one of the same kind and name — a precedence rule an agent could not infer elsewhere.

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

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

It is one dense paragraph, but it is front-loaded with the resource and its subtypes before moving to the parameters. Every clause carries information (the four subtypes, the override rule, the search fields, the rationale for metric expressions); only the closing sentence about agreeing with team reports is slightly redundant with the earlier metric explanation.

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?

Both optional parameters are documented in the schema and enriched in prose, there is no output schema to explain, and the description covers what kinds of definitions come back and how connection scoping works. An agent has everything needed to call it correctly and interpret the result.

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

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

Schema coverage is 100%, so baseline would be 3. The description goes beyond the schema by spelling out the inheritance/override behaviour of connectionId and by stating that search matches on name, synonym or description — the synonym matching in particular is not in the schema's "Words to look for" wording.

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

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

The description opens with a specific verb+resource ("The organisation's shared definitions") and immediately enumerates the four subtypes returned: metrics, datasets, relationships and admin notes. It is clearly distinguishable from siblings like fastero_run_sql (executes) or fastero_save_definition (writes) because it frames itself as the read side of the definition store.

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 the triggering context explicitly — "for writing SQL about a business question" — and explains that a query built from a metric agrees with the team's reports, which tells the agent when this lookup is worth doing. It never names an alternative (e.g. fastero_list_connection_schemas for raw table structure) or says when not to use it, so it stops short of full routing guidance.

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

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

Annotations already cover the safety profile (readOnly, non-destructive), and the description adds substantial context beyond them: status only flips when the run ends, nothing is retried, an error field reports the first failing cell with an example format, a foreign runId returns "Notebook run not found.", and permission scope is spelled out.

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 purpose, then the return fields, then behavioral caveats and alternatives — a sensible ordering with little waste. The sentence about fastero_run_notebook returning an in-progress run 'unless the run has said running for over an hour' is dense and slightly harder to parse than the rest.

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

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

There is no output schema, so the description carries the return contract itself — it enumerates runId, status values, timestamps, durationMs and the error shape. Combined with the not-found behavior and permission note, an agent has everything needed to call and interpret this tool.

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

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

Schema description coverage is 100% and each parameter already names its source tool (fastero_run_notebook, fastero_list_projects, fastero_list_notebooks), so the schema does the heavy lifting. The description adds only the cross-notebook/project failure behavior, which is a modest increment over structured data.

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

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

Opens with a specific verb+resource: checks the progress of a notebook run that fastero_run_notebook started. It explicitly distinguishes itself from fastero_run_notebook (which starts runs) and fastero_read_notebook (which reads cell outputs), so an agent can route between the three 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?

Gives explicit when-to-use (poll a started run), alternatives (fastero_run_notebook to re-run, fastero_read_notebook for outputs once finished), and an edge case (a run 'said running' for over an hour). It also states the access precondition — any project member including viewers can check a run.

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 past the readOnlyHint/destructiveHint annotations by disclosing side-effect absence ('Nothing is run and no widget rows are read'), the exact failure mode ('A page deleted or not in this project answers "Page not found"'), and the permission model ('Any project member, viewers included, can read it'). Those are the auth and error-behavior details an agent cannot infer from 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?

Purpose and payload are front-loaded in the first clause, and the alternative-tool routing follows immediately. It is one dense run-on paragraph packing many clauses (widget fields, error counts, permissions, error string), which is efficient but could be broken up for scannability.

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

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

With no output schema, the description carries the return-shape burden and does so fully — field names, nested widget structure, and the recentErrors payload with timestamps. Permission scope and the not-found response complete what an agent needs before calling.

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

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

Schema coverage is 100% and both parameters already document their provenance (from fastero_list_pages and fastero_list_projects). The description adds only indirect meaning, via the 'not in this project' error case for projectId, so the baseline 3 for schema-covered parameters is right.

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 ('Read one hosted page in full') and immediately enumerates what comes back: HTML, widgets with name and widgetId, url, noteEnabled, refresh, and recentErrors with timestamps. It also explicitly distinguishes itself from fastero_update_page, fastero_list_pages, and fastero_show_page, so an agent can route correctly 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?

Names three alternatives with the exact condition that selects each: update_page replaces the HTML, list_pages lists without it, show_page shows one live without pulling HTML into the conversation. That is an explicit when-to-use / when-not-to-use map rather than implied 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 past readOnlyHint/destructiveHint: it discloses the data-provenance cascade (recent cache, then a fresh run of the saved query, then last stored copy, with spreadsheet and notebook-cell special cases), truncation with truncated=true, refusal behavior for undeclared or deleted widgets, 'Page not found' for deleted or cross-project pages, and that any project member including viewers can read it.

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 return shape, which is good, but the rest is one dense run-on paragraph blending provenance, errors, permissions and truncation into semicolon-chained clauses. Every fact earns its place, yet the structure makes it harder to scan than it needs to be.

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 and no annotations beyond read-only hints, the description still covers return fields, freshness semantics, truncation, error responses and authorization. An agent has everything needed to call it and interpret the result.

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

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

Schema coverage is 100%, so the baseline is 3; the description adds real meaning for `name` by requiring it to be a name the page actually declares (cross-referencing fastero_get_page) and by describing the refusal that follows an undeclared or deleted widget name. projectId and pageId are left entirely 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 (return the current rows of one widget declared by a hosted page) and immediately gives the return shape { rows, lastUpdated, truncated }. It explicitly distinguishes itself from fastero_get_page (HTML and widget names) and fastero_show_page (display).

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 two closest siblings and what each is for, so the agent can route correctly, and discloses that the tool is marked app-only so the data stays out of the conversation. It stops short of stating an explicit 'use this instead of X when Y' rule, but the alternatives are clear.

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 state readOnlyHint=true/destructiveHint=false, yet the description adds real behavioral context beyond them: a deleted project still returns with isDeleted true, an unknown id returns 'Project not found' rather than erroring, and any project member including viewers can read. Those edge-case and permission facts are exactly what an agent needs and cannot get from 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?

Front-loaded with the payload contents and then the sibling routing, which is the right order. It is a single dense paragraph with many sibling references; every clause carries information, but the density makes it slightly harder to scan than an ideal definition.

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

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

There is no output schema, yet the description enumerates the returned fields, the deleted-project marker, the not-found response, and the permission scope. Combined with the two fully documented parameters, an agent has everything needed to call it and interpret the result.

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

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

Schema coverage is 100% and both parameters already document their provenance (projectId from fastero_list_projects, pythonProjectId from fastero_list_python_projects). The description adds only indirect meaning, noting that entrypoint ids are the values consumed by fastero_run_python_project and fastero_set_python_schedule, but nothing about the two parameters themselves beyond the schema. Baseline 3 is appropriate.

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 ('Read one Python project in full') and then enumerates exactly what is returned: name, description, source, environment, entrypoints, localFiles. It explicitly distinguishes itself from fastero_list_python_projects, fastero_list_python_files and fastero_list_python_runs, so an agent can pick it 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 a concrete when-to-use ('to find an entrypoint id or see what is stored') and names the alternative for each neighbor: list_python_projects for the id, list_python_files for folder-by-folder listing, list_python_runs for run history. This is explicit routing, not implied usage.

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

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

Annotations only declare readOnlyHint=true/destructiveHint=false; the description adds substantial context beyond that: the run stores the last 60,000 chars of each stream and this returns the last 50,000, so t​​he tail (where tracebacks live) is kept, truncated=true plus a note when the head was cut, and the permission model (any project member, viewers included).

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 return contract, then truncation semantics, then id sourcing and exclusions, then permissions — a logical order with little waste. Slightly long at five sentences, and the 60,000/50,000 detail, while useful, is the densest part.

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, so the description must describe the return value and it does: stdout, stderr, truncated flag, and an explanatory note. Combined with the empty-result case and permission model, an agent has everything needed to call it and interpret the result.

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

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

Schema description coverage is 100%, and each parameter already names its source tool, so the schema carries the load and baseline 3 applies. The description's only additional semantics is that a runId from another Python project yields no output, which is a modest increment.

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 (read a finished Python run's printed output) and enumerates exactly what comes back: stdout, stderr and truncated. It is clearly separable from fastero_list_python_runs (status/error without the log) and fastero_read_python_file (files the run saved).

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: get runId from fastero_list_python_runs, use that tool instead if only status/error is needed, use fastero_read_python_file for saved files. It also names the when-not case — a queued/running run or a runId from another Python project returns 'This run has no saved output'.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered; the description adds real value on top by naming the concrete fields returned (name, SQL text, conn, definitionsUsed) and confirming that executing the query is explicitly out of scope. No cost, latency, or auth detail, but the key behavioral claim is unambiguous.

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

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

Three short sentences, front-loaded with the core action and return payload, then the run_sql disambiguation and the report relationship. No sentence is 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?

With no output schema, the description correctly compensates by listing the returned fields, and it notes the report linkage via fastero_get_report. It does not describe errors for a missing/foreign queryId, which would be the last piece of context an agent might want.

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

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

Schema description coverage is 100%, and both parameters already document where their ids come from (fastero_list_queries, fastero_list_projects). The description adds no further parameter semantics, so the baseline 3 applies.

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

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

States a specific verb and resource ("Read one saved query") and enumerates the payload it returns: name, SQL text, connection (conn), and definitionsUsed. It explicitly separates itself from fastero_run_sql, which is the sibling an agent would most plausibly confuse it with.

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?

"Nothing is run: fastero_run_sql runs SQL and returns rows" gives an explicit when-not plus the alternative to pick instead. It also implies the queryId comes from fastero_list_queries. It stops short of stating the list-vs-get selection rule outright, so it is strong but not exhaustive.

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 cover the read-only safety profile, and the description adds genuinely new behavioral facts: "Nothing is run" (reading a report does not execute its query), the payload contents (name, type, widgetType, chartType, assignments, display settings, query id, url), Vega-Lite special-casing via chartProps.vegaLite with chartRevision and last-five chartHistoryNotes, and that spreadsheet-backed widgets carry their rows.

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

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

Purpose is front-loaded in the first clause and nearly every clause carries a distinct fact. It is a dense single paragraph with heavily nested parentheticals ("its query (the id of the saved query it reads, whose SQL fastero_get_query returns) and url"), which costs some readability.

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

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

There is no output schema, so the description bears the full burden of describing the return payload, and it does so thoroughly, including the Vega-Lite variant and revision history. Combined with the sibling routing, an agent has everything needed to call it and interpret the result.

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

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

Schema description coverage is 100% and both parameters already document their provenance (fastero_list_reports / dashboard items; fastero_list_projects). The description body adds no further parameter-level detail, so the baseline 3 applies — the schema carries this dimension.

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?

Specific verb plus resource ("Read one report"), and it immediately defines what a report is — "a chart, table, number, map or text block that dashboards place" — so the agent knows the object model. It distinguishes itself from the near-name siblings (fastero_get_dashboard, fastero_show_report, fastero_list_reports) by naming them and their distinct roles.

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?

Three routing alternatives are given: fastero_get_dashboard identifies which reports a dashboard places, fastero_show_report renders the chart itself, and fastero_get_query returns the SQL behind the referenced query. The selection conditions are implied by those roles rather than phrased as explicit "use X when Y", so it falls just short of a 5.

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

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

Annotations only declare it a safe read; the description adds substantial context beyond that: live status is verified against the app's server, files are truncated past 50,000 chars each / 300,000 total and flagged with truncatedFrom, viewerUrl is member-only, a missing/deleted app returns "Streamlit app not found.", and any project member including viewers may call it.

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 verb and resource, and every sentence carries information — field inventory, use cases, alternatives, truncation limits, sharing, not-found behavior, permissions. It is a single dense block rather than clearly segmented, which costs a point but 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?

There is no output schema, so the field enumeration is load-bearing and thorough. Combined with truncation limits, permission scope, error behavior and sibling routing, an agent has everything needed to call this and interpret the result 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 100% and both parameters already document their provenance (appId from list_streamlit_apps, projectId from list_projects), so the baseline is 3. The description names appId in the field list but adds no format, syntax or constraint detail beyond what the schema provides.

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

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

"Read one Streamlit app with its files" gives a specific verb, resource and scope, then enumerates the exact returned fields (status, alwaysOn, errorMessage, source, viewerUrl, per-file path/name/content). It explicitly separates itself from fastero_list_streamlit_apps (no files) and fastero_get_streamlit_app_logs (start-up output), so an agent can pick correctly 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?

Two concrete use cases are stated: reading an app's code before changing it, and checking whether a start has finished. The alternatives are named with the condition that selects each — list_streamlit_apps for metadata only, get_streamlit_app_logs for startup/pip errors — and sharing is redirected to fastero_invite_to_project since there is no public link.

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 establish readOnlyHint/destructiveHint; the description adds real behavioral detail beyond them — retention window (first five minutes), that the log is cleared at every start, and that secret values are redacted. It does not disclose the failure mode when no recent start exists or a log has already been aged out.

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

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

A single dense sentence that front-loads what is read and follows with the scoping and safety constraints; every clause (contents, time window, clearing, redaction) carries information an agent needs.

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 usefully characterizes what the returned text will contain and how it is bounded. It is nearly complete, missing only what the agent sees when there is no recent start or the log has been emptied.

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

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

Schema description coverage is 100% and both parameters already document their source (fastero_list_streamlit_apps, fastero_list_projects). The description adds no parameter-level meaning beyond the schema, so the baseline 3 applies.

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

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

States a specific verb (Read) and resource (the start-up log of a Streamlit app's most recent start), and enumerates the log's contents (file sync, pip install including pip errors, Streamlit's first lines). This scopes it away from the adjacent siblings get_streamlit_app (metadata) and get_python_run_log (a different runtime).

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?

Clearly frames the applicable context: it covers the first five minutes after a start and the log is cleared at each start, which effectively tells the agent when this tool is useful versus futile. It stops short of naming an alternative for older starts or a different diagnostic tool, so no explicit when-not/alternative 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?

Far beyond what the annotations provide: it discloses the two-phase confirmation flow, that no email is sent by the call, the 7-day expiry for both confirmation and link validity, escalation to organisation-wide Viewer access, the immediate-add path for existing members, and the 409/429 failure conditions with their rate-limit accounting. These are exactly the mutation consequences destructiveHint=true and openWorldHint=true imply but do not explain.

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 clause carries operational weight, but the middle section packs many facts (access scope, membership shortcut, rate limits, return shape) into one dense run-on, which reduces scannability 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?

No output schema exists, yet the description documents the return payload (inviteId, status, confirmUrl, expiresAt, 'added'). For a mutation tool with 4 parameters, annotations, and no output schema, it supplies everything an agent needs to call and interpret 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 coverage is 100%, so the baseline is 3, but the description adds real meaning beyond it: what the email parameter triggers at confirmation (shown to the confirmer before anything sent) and the observable outcome (inviteId plus 'awaiting_confirmation'/'added' status). The appId and dashboardId landing targets are left to the schema, which is acceptable.

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

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

The first sentence states a specific verb and resource ("Ask to invite someone by email to view a project") and the description names the sibling it is not (fastero_share_dashboard), so an agent can distinguish it from the share-link tool immediately.

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

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

It explicitly names when to use it ("people who should sign in to Fastero") and the alternative with its condition ("for a link anyone can open without an account, use fastero_share_dashboard"), plus the role prerequisite (Owner or Admin). Nothing is left 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 already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds genuinely useful context beyond them: destination creation is admin-only and impossible via any tool, and destinations can be 'disabled with the reason', signalling that a non-active status carries diagnostic text.

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, zero filler, front-loaded with what is listed before the operational constraints. The parenthetical explanation of 'claude_routine' and the pointer to set_job_callback both earn their space.

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 and no parameters, the description is the only source of return-shape information, and it supplies it fully, including the semantics of each status value and how the result feeds the next tool. Nothing needed to call this correctly is missing.

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

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

Zero parameters, so the schema carries nothing to misread and the baseline is 4. The description instead documents the shape of the result (name, kind, host, status), which is the more useful information here.

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

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

States a specific verb and resource ('List where this organisation's job callbacks can go') and enumerates the returned fields — name, kind, host, status — with an inline gloss of the non-obvious enum value 'claude_routine'. It also names the downstream sibling fastero_set_job_callback, so an agent can distinguish it from the many other list_* tools 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?

It gives a clear use route ('fastero_set_job_callback takes a name from here') and rules out a tempting but impossible action ('An admin adds destinations in Settings → Developers → Callbacks; no tool can add one'), which prevents an agent from hunting for a create tool. It stops short of an explicit when-not against any listed sibling, since no alternative list tool exists.

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's job is to add context, which it does: it states the scope (all projects in the organisation), the exact fields returned and the fields deliberately withheld, and the permission floor ('Any member of the organisation can list them'). That is unusually complete disclosure for a read-only listing 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?

Front-loaded with the purpose and the connectionId payoff, and the exclusion of credentials is stated before the alternatives. The datasource parenthetical and the orgId closing sentence duplicate information already in the schema, which is the only waste in an otherwise tight 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?

There is no output schema, so the description carries the return-value burden itself, and it does: _id, name, datasource, database (including the BigQuery project-id caveat), creator and timestamp. Combined with the read-only annotations and the org-scoping note, an agent has everything needed to call it and interpret the result.

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

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

Schema coverage is 100% and the single orgId parameter is already documented as defaulting to the key's organisation. The description's closing sentence ('orgId can be left out: it can only be the organisation this key belongs to') restates that rather than adding new semantics, so the baseline 3 applies.

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

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

Starts with a specific verb and resource ('List every data connection in this organisation, from all its projects') and immediately ties the output to the connectionId consumed by fastero_run_sql, fastero_list_connection_schemas, fastero_create_query and fastero_show_chart. An agent can tell exactly what it gets and why it matters 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 the agent: use this to pick a connectionId, use fastero_get_connection for settings and last test, and fastero_list_connection_schemas for tables. The exclusion of credentials/hosts/test results makes the boundary with fastero_get_connection 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, and the description goes further with live-read-on-every-call, no paging, long answers on large databases, and even the exact refusal messages ('Insufficient rights', 'Connection not found'). That permission and error disclosure is genuinely useful, but return-shape and paging already carry the main behavioral weight for a read tool, so it sits at a solid mid-high rather than exceptional.

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 verb and scope, then alternatives, then behavior, then permissions — a logical order with no filler. It runs long for a single-parameter read tool, but nearly every clause carries distinct information, so the density is justified.

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

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

No output schema exists, yet the description spells out the return structure (schemas → tables → type and column names), plus the permission model, the exact error strings, and the no-paging characteristic. An agent can call this correctly and interpret the response without further exploration.

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

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

Schema coverage is 100% and the schema already explains that connectionId comes from fastero_list_connections or fastero_create_file_connection. The description adds only the adjacent fact that an uploaded file's connection holds one table, which is contextual rather than parameter-level; the schema does the heavy lifting, so baseline 3 applies.

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

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

States a specific verb and resource — 'List the schemas, tables and columns that a connection's database login can see' — and pins the scope to what the login can see, which is the exact axis an agent needs. It is unmistakably distinct from sibling list tools like fastero_list_connections or fastero_get_connection.

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 usage: 'Use it to find table and column names before fastero_run_sql or fastero_create_query,' and then rules out the two nearest neighbours by stating what fastero_get_definitions and fastero_get_connection hold instead. When-to-use and when-not-to-use are both covered without 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 already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds access context ('Dashboards are shared with everyone in the organization') and enumerates the returned fields, which is meaningful information beyond 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?

Front-loads purpose and ordering, then return contents, then sharing, then related tools. Efficient overall, though the itemized return-field list is slightly dense; each sentence still 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?

With no output schema, the description carries the return-value burden and does so by enumerating the returned fields (_id, name, description, author, filters, tabs, items with reportId). It omits any pagination or result-size guidance, which is the only notable 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 100% and the schema already documents projectId (from fastero_list_projects). The description adds no syntax or format detail beyond that, so the baseline of 3 applies.

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

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

States a specific verb and resource ('List a project's dashboards') plus an ordering guarantee ('oldest first'). It also names the sibling tools it is not (fastero_get_dashboard, fastero_list_reports), so an agent can distinguish it without opening other 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?

Points to fastero_get_dashboard for reading one dashboard with its link and refresh, and to fastero_list_reports for the chart definitions, making the routing conditions clear. It stops short of explicitly stating when NOT to use it or listing prerequisites, but the alternative-routing is well 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?

With annotations only declaring readOnlyHint/destructiveHint, the description carries the burden of return-value disclosure, and it does so richly: fileId, name, folder path (with the null-at-top-level semantics), type, size in bytes, last-updated, and pathInNotebook with concrete usage examples (pd.read_csv/pd.read_excel). It omits whether subfolders are traversed recursively, ordering, and any size/result limits, which are real behavioral gaps for a listing 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?

A single dense paragraph that is front-loaded with what gets listed, then what comes back, then the sibling exclusions. Nearly every clause earns its place (pathInNotebook examples, folder-path null semantics), though the return-field enumeration is delivered as one long running clause that 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?

For a read-only, single-parameter list tool with no output schema, the description is nearly sufficient: it names the resource scope, the return payload, and the alternatives. The remaining gap is behavioral detail on enumeration scope (recursive vs top-level only) and result limits, which an agent would otherwise have to discover by trial.

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?

Only one parameter, and the schema already documents it at 100% coverage, including its provenance ('from fastero_list_projects'). The description adds nothing beyond 'in a project' for that parameter. Baseline 3 applies since the schema does the heavy lifting.

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

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

States a specific verb and resource ('List the files in a project') and immediately enumerates the resource types covered: uploaded spreadsheets, CSVs, PDFs, documents, plus assistant-produced workbooks, documents, PDFs and slides. It explicitly contrasts with sibling tools ('A Python project's code is listed by fastero_list_python_files; notebooks, saved queries and dashboards have list tools of their own'), so an agent can distinguish it from fastero_list_python_files, fastero_list_notebooks, fastero_list_queries and fastero_list_dashboards 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 away from this tool for Python code, notebooks, saved queries and dashboards, pointing to the correct alternatives. It also implies the reason to call it (to obtain the fileId consumed by fastero_read_file, fastero_rename_file, fastero_delete_file). It stops short of stating the positive trigger ('call this to find or open a file in a project') as a standalone instruction, but the context is clear.

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 safety is covered. The description adds useful behavioral context: the most-recently-changed ordering and the exclusion of personal notebooks; it does not mention pagination or limits, but that is a minor gap for a read-only list 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 a single dense sentence with zero waste, front-loaded with the action, ordering, and returned fields, followed only by the necessary sibling and exclusion notes.

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 read-only list tool with full schema coverage and no output schema, the description provides the ordering, returned fields, excluded scope, and sibling alternatives. Nothing an agent needs in order to call it correctly is missing.

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

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

Schema coverage is 100%, so baseline is 3; the description compensates by explicitly stating what _id means and that it is the notebookId other notebook tools accept, which is not in the schema. It does not add semantics beyond the projectId parameter, which is already fully documented.

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

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

The description states a specific verb and resource ('List a project's notebooks'), the ordering ('most recently changed first'), and the returned fields with a cross-reference for _id. It also explicitly distinguishes itself from fastero_read_notebook and notes the exclusion of personal notebooks and separate Python/Streamlit list tools.

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

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

It explicitly tells when to use this tool over fastero_read_notebook ('reads one's cells') and explains that personal notebooks are not listed, while pointing to fastero_list_python_projects and fastero_list_streamlit_apps as alternatives. Nothing is left 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 already establish readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds real behavioral value beyond that: the sort order, the explicit exclusion of HTML, and the exact fields returned (_id, name, widgets read by name, url). It stops short of mentioning pagination or result limits, which is the only gap for a list endpoint.

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

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

Two dense sentences with the core operation front-loaded, and the alternative tools packed into a trailing sentence rather than scattered. The nested appositive for url ('the page where a signed-in project member opens it') is slightly ornate for the value it adds.

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

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

There is no output schema, so the description must carry the return shape, and it does enumerate the returned fields and the HTML exclusion. The missing piece is any statement about result volume or pagination, which an agent listing a large project would need.

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

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

Schema description coverage is 100% and the single projectId parameter is fully documented in the schema, including its provenance from fastero_list_projects. The description adds nothing parameter-specific, so the baseline 3 applies.

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

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

States a specific verb and resource (list a project's hosted pages) plus two distinguishing qualifiers: sorted most-recently-changed-first and returned without HTML. It also names the sibling tools it is not (get_page, show_page), so an agent can separate it from the other page tools 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 the agent: get_page 'reads one's HTML and recent errors' and show_page 'shows one live in the conversation', leaving list as the choice when you only need the inventory. The parenthetical that _id is 'the pageId other page tools take' also tells the agent when to call this first as a discovery step.

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=true; the description goes further by disclosing the Owner/Admin permission requirement and enumerating the fields returned including the two distinct status values and confirmUrl semantics. That is behavioural context the structured data does not carry.

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 definition and exclusions before the return-value detail, and every clause is informative. Some sentences are heavily nested (the status/confirmUrl clause), which costs a little readability but no sentence is 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?

With no output schema, the description compensates by describing the returned fields and status values, and it covers the auth prerequisite and the exclusion rules. An agent has everything needed to call it and interpret the result.

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

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

Schema coverage is 100% and the single projectId parameter is already documented as coming from fastero_list_projects, so the description adds nothing about parameter meaning. Baseline 3 applies when the schema does the work.

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?

Specific verb (List) plus resource (a project's open invites) with an explicit definition of what 'open' means — emailed-and-unaccepted plus requested-and-unconfirmed. It also names the exact boundary against accepted, cancelled and lapsed invites, so the agent can tell this apart from any cancel/mutation sibling.

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

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

Gives two concrete use cases (fetching the inviteId that fastero_cancel_project_invite consumes, and checking whether a requested invite was confirmed and sent) plus an explicit exclusion list. The alternative tool is named with the condition that links the two.

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 safety is covered. The description adds value beyond that by disclosing what the call returns (project ids plus the current organization and account identity), which is genuine behavioral context for a tool with 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?

Two sentences, front-loaded with the core action and return content, followed by the useful hierarchy note. Nothing is wasted, though the second sentence is slightly run-on.

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

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

For a zero-parameter list tool with no output schema, the description covers the action, the returned fields and the downstream relationship to projectId-consuming tools. That is sufficient to invoke it correctly; only exhaustive return detail is absent.

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

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

The tool takes zero parameters, so the baseline is 4 and there is nothing for the description to document. No misleading parameter information is present.

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

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

States a specific verb and resource ('List the projects') with scope ('in this organization') and names what is returned (ids). It also differentiates itself from the many list_* siblings by explaining the domain hierarchy — projects contain queries, reports and dashboards — so an agent can place it 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 second sentence gives clear usage context: it is the source of the projectId that query/report/dashboard tools consume, so an agent knows to call it first. It stops short of explicit exclusions or naming concrete alternatives (e.g. list_python_projects), so it is a 4 rather than 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?

Goes well beyond the readOnlyHint/non-destructive annotations: no recursion (so outputs/report.md only appears when outputs is listed), repo-linked projects listed from the branch plus local writes with .git/.venv/node_modules/__pycache__ excluded, nonexistent folder returns empty, out-of-project paths refused, and viewer-level access allowed. These are exactly the edge behaviors an agent needs before calling.

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, resource and return shape, then usage, then alternatives, then edge cases — good ordering with no filler. It is dense with multi-clause sentences (the repo/ignore-list sentence packs four ideas), which slightly taxes readability but every clause 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?

With no output schema, the description supplies the return entry structure { name, type, path } and covers recursion, filtering, failure modes, and permissions. An agent has everything needed to call this correctly and interpret results.

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

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

Schema coverage is 100% and already documents all three parameters, including 'omit for the project root'. The description reinforces the path default ('the top level by default, or the folder given as path') and adds that the path must be a non-recursive folder scope, which is meaning beyond the schema, though it does not add syntax 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?

States a specific verb and resource ('List one folder of a Python project's code and files') plus the exact entry shape returned. It also explicitly separates itself from fastero_list_files and fastero_get_python_project, so an agent can pick it without opening sibling 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?

Gives a concrete use case ('Use it to find the path that fastero_read_python_file, fastero_write_python_file and fastero_ensure_python_entrypoint take') and names the two alternative list tools with the condition that selects each. Nothing is left 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 already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds genuine behavioral context beyond that: ordering (newest first), exclusion of deleted items, the returned field set, and the fact that the _id maps to pythonProjectId used by other Python tools.

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 heavily information-dense with no filler sentences. The single long sentence is slightly run-on and packs clauses together, but every clause (ordering, exclusion, returned fields, sibling disambiguation) 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?

There is no output schema, so the description correctly carries the burden of describing return values (_id, name, source, environment, entrypoints, runnable files by id). Combined with the annotations covering the read-only profile, an agent has everything needed to call it correctly.

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

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

Schema description coverage is 100% and projectId is fully documented in the schema ('The project's id, from fastero_list_projects'), so the baseline of 3 applies. The description adds no additional parameter syntax, format, or edge-case behavior for projectId.

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

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

States a specific verb and resource ('List a project's Python projects (script workspaces)') and immediately differentiates itself from fastero_list_python_files by scope (projects vs. files). An agent can distinguish it from fastero_get_python_project and fastero_list_projects 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?

Names the alternative sibling (fastero_list_python_files) and its distinct scope, plus the project-scoping requirement via projectId. It lacks explicit 'when not to use' guidance versus fastero_get_python_project for single-project lookups, but the context is clear.

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 read-only, non-destructive profile, and the description goes well beyond them: it discloses the 50-item cap, newest-first ordering, absence of paging, the full status vocabulary with an explicit note that succeeded/failed/cancelled are terminal, the triggeredBy categories, and the savedFiles artifact. That is substantive behavioral context an agent cannot get from 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?

A single sentence that front-loads the key constraint (50 most recent, newest first, no paging) before the field enumeration. The trailing field list is long but every clause earns its place because there is no output schema to convey return shape.

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 describing returns, and it does so thoroughly — run identity, entrypoint, status semantics, trigger origin, timestamps, error, and output files. Combined with the schema's parameter docs, an agent has everything needed to invoke and interpret the call.

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

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

Schema description coverage is 100% and both parameters (projectId, pythonProjectId) are documented in the schema with their source tools. The description adds no syntax or format detail beyond that, so the baseline 3 is appropriate.

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?

Names a specific verb and resource (list Python runs), pins the scope (50 most recent, newest first, no paging), and explicitly identifies the sibling fastero_get_python_run_log as the consumer of the returned _id. An agent can distinguish this from the many other list_* siblings without opening a 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?

Clear context: this is the way to enumerate recent runs, and its _id feeds fastero_get_python_run_log, which routes the agent between the two. It also rules out paging. It stops short of an explicit when-to-use/when-not statement against other list tools, so it lands just below the top.

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 the read-only, non-destructive profile, and the description adds real behavioral context: results are ordered newest first, the _id is the queryId other tools accept, and conn is null once the connection is deleted. This output/nullability detail is valuable given 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 compact sentences, front-loaded with the core action and scope, then return fields, then the disambiguation. No filler.

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

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

Despite no output schema, the description enumerates the returned fields and their semantics (name, SQL text, conn with name/type, nullability), plus ordering and the routing to run_sql. An agent has everything needed to call and interpret this list 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 100% and the single projectId parameter is already documented as coming from fastero_list_projects. The description adds no further parameter syntax or format detail, so the baseline 3 applies.

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

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

States a specific verb (List) and resource (a project's saved queries) and immediately distinguishes itself from fastero_run_sql. An agent can identify the tool's scope 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?

Explicitly routes the agent away from fastero_run_sql ('runs SQL without saving it'), clarifying the saved-vs-ad-hoc distinction. It does not mention other query siblings like fastero_get_query or fastero_create_query, so guidance is clear but not exhaustive.

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 safety is covered; the description adds real value by disclosing the returned field set and, importantly, the negative behavior that text blocks are omitted. It stops short of stating pagination or result-size behavior, which matters for a list tool.

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

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

Three sentences, front-loaded with purpose, then return contents, then routing. The field enumeration is dense but each element is informative; there is no filler, though the middle sentence is long and could be parsed more easily as a list.

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-shape burden and does so by naming the fields and the reportId linkage other tools need. The remaining gap is pagination/volume behavior for a list call, which an agent might need to know.

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 one parameter at 100% schema coverage, the schema already explains projectId and its provenance (fastero_list_projects). The description adds no further constraint or format detail on the input; its detail about _id/reportId concerns output rather than the parameter.

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

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

The description opens with a specific verb and resource ('List the widgets (reports) in a project') and then enumerates exactly which fields come back. It distinguishes itself from fastero_get_report (full read) and fastero_get_dashboard (text blocks), so an agent can separate it from the read-one siblings without inspecting schemas.

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

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

It explicitly routes the agent: use fastero_get_report to read one report in full, and go to fastero_get_dashboard for a dashboard's text blocks. That covers the main alternative and the exclusion, though it doesn't state when listing is preferable (e.g., discovery before update) or mention filtering/paging limits.

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 safety is covered; the description adds real behavioural detail beyond them: a 100-item truncation cap, an ownership filter excluding colleagues, and that a failed run's error is surfaced. It stops short of auth requirements or pagination mechanics, so it is strong but not exhaustive.

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 action and scope in the first sentence, then routing constraints. The enumeration of schedule kinds is dense but each item earns its place by disambiguating siblings; the third sentence's trigger-vs-schedule distinction is the only part that 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?

With no output schema, the description correctly compensates by describing the return payload (timetable, enabled state, next/last run, last error). Combined with the scope limits and the sibling routing, an agent has everything needed 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?

The single parameter (projectId) is fully documented in the schema at 100% coverage, and the description does not restate or extend its meaning beyond the org-wide scope it already implies. Baseline 3 is appropriate when the schema does the heavy lifting.

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

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

States a specific verb and resource ('List your own schedules') and then enumerates exactly which objects count (dashboard emails, alerts, notebook runs, repeated agent runs), which is critical for disambiguating from the many sibling list_* tools. It also names the field each item carries (scheduleId) and who consumes it (fastero_set_schedule_enabled).

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 scopes usage ('your own schedules', 'colleagues' schedules are not', 'the 100 newest are listed') and routes the agent away from this tool when the object is actually a trigger: 'A Python project's schedule, and a dashboard's automatic refresh, are triggers instead, in fastero_list_triggers.' That is a named alternative plus the condition that selects 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?

Goes well beyond the readOnlyHint/destructiveHint annotations by disclosing that values are never returned by any tool (though run code can print one), that listings are scoped to the key's organization, what fields are included, and the exact role requirements. This is the kind of context annotations cannot carry.

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 and alternatives are front-loaded in the first sentence, permissions at the end. It is somewhat dense and run-on in the middle ('each with its _id, name, type...'), but every clause adds real 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?

With no output schema and no parameters, the description compensates by describing the scope of the listing, the fields returned, the secrecy guarantee, and the permission gate. Nothing material is missing 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?

Zero parameters, so the baseline is 4. The description usefully reinterprets the response fields (id, name, type, project/environment scope, timestamps), though it is not required to describe 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?

States a specific verb and resource ('List the Secrets of the organization this key belongs to') and explicitly names the sibling tools it serves (fastero_update_secret, fastero_create_secret). An agent can distinguish it from the other secret-related tools without opening a 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 explicit when-to-use conditions: to find the id that fastero_update_secret takes, or to check a name before fastero_create_secret. It also states the permission model (owners/admins/editors can list, viewers are refused), which tells the agent when the call will fail.

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, and the description is fully consistent while adding substantial context the annotations cannot: deleted apps are excluded, and any project member including viewers can call it. It enumerates the returned fields and their semantics (status values, errorMessage, source/branch/sync state, viewerUrl), which matters 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?

Purpose and scope are front-loaded in the first clause, and nothing is redundant. The middle field enumeration is a long run-on list, but it earns its place given the absence of an output schema; slightly tighter grouping would read better.

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

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

With no output schema, the description compensates by documenting the returned fields and their meanings, and it covers permissions, exclusions, and the alternatives. Nothing an agent needs in order to choose and call this tool 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?

There is a single parameter with 100% schema description coverage pointing to fastero_list_projects, so the schema already carries the semantics. The description only implies the project scoping; it adds no format or sourcing detail beyond what the schema states. Baseline 3 applies.

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

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

States a specific verb and resource ("List a project's Streamlit apps") plus an explicit scope qualifier ("without their files"), which immediately separates it from fastero_get_streamlit_app and the log reader. An agent can distinguish it from all siblings 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?

"Use it to find an app or see which are up" gives the positive selection condition, and the next sentence names both alternatives with the exact cases that select them (reading files / checking live status vs. reading start-up output). It also states exclusions: deleted apps are not listed.

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 safety is covered; the description adds real context beyond that: which fields each item carries, that cron is read in UTC, and that the cron lives only here rather than on the Python entrypoint. It does not discuss volume/pagination for a list across the whole org, which is the main remaining gap.

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

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

Front-loaded with the scope and enumeration, then returns, then the sibling redirect. Dense and mostly waste-free, though the 'py:<pythonProjectId>:<entrypointId>' naming digression is lengthy relative to how often it matters.

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 compensates by enumerating the returned fields (_id, name, type, enabled, cron) and their semantics. Combined with the sibling redirect and the UTC note, an agent has everything needed to call and interpret this tool.

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

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

There is a single orgId parameter already documented at 100% schema coverage, including the default behavior, so the schema does the heavy lifting. The description never references orgId, but no additional meaning is needed given 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 ('List every trigger in the organization') and enumerates the concrete trigger kinds covered: Python schedules, dashboard/page refreshes, and DB/Kafka/webhook watchers. It also names the distinguishing sibling (fastero_list_schedules) so the boundary 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?

Explicitly routes the agent: 'Dashboard emails, alerts and notebook runs are schedules instead, in fastero_list_schedules.' It also connects the returned _id to fastero_enable_trigger and fastero_disable_trigger, telling the agent what to do with the output.

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 a non-read-only, non-destructive mutation, and the description adds real context beyond them: the widget tracks the notebook's latest run, so scheduled runs keep it current, and it propagates to dashboards, share links, emails, and pages. It also states the return value (_id and url). It does not say whether re-pinning the same cell creates a duplicate widget or replaces the existing one, which is the main remaining behavioral gap.

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

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

Front-loaded with the action and its output, then prerequisites, then index semantics, then return value. Every sentence is relevant, though the cellIndex sentence partially duplicates the schema description and could be trimmed.

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

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

For a 9-parameter tool with a nested object and no output schema, the description covers the prerequisite, result-source semantics, index convention, chart-assignment requirement, optional dashboard placement, and the return shape. Minor gaps remain around duplicate-pinning behavior and non-tabular Python cell results, but nothing essential to calling 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 100%, so the baseline is 3. The description mostly restates schema content (cellIndex counting from 0 including markdown cells; charts need assignments naming plotted columns; table is the default). The one genuine addition is tying cell ordering to 'the order fastero_read_notebook gives them', which helps the agent derive a valid index.

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 ('Make a dashboard widget from a notebook cell's result') and pins down which cell results qualify (SQL rows, or the last table a Python cell shows, whether from a DataFrame on the last line or via display()). This is clearly distinct from siblings like fastero_save_chart, fastero_show_chart, and fastero_publish_widget_api.

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

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

Gives a concrete prerequisite ('Run the notebook first (fastero_run_notebook) so the cell has a result') and names the related schedule tool. It also explains that dashboardId optionally places the widget on a dashboard too. It never explicitly says when NOT to pin (e.g., versus saving a chart from a query), so it stops just short of full routing guidance.

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

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

Well beyond the annotations: it discloses the response shape ({rows, lastUpdated, truncated}), the X-Endpoint-Key auth header, data-freshness semantics per widget type, that anyone holding the key can read until unpublished, that owners are emailed, and that the key is returned only once because only its hash is stored. These are exactly the non-obvious traits an agent cannot infer from destructiveHint/openWorldHint.

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 purpose and alternative, and nearly every clause carries new information (eligibility, freshness, key handling, return fields). It is a single dense paragraph with heavy clause-stacking, which slightly hurts scannability for an agent parsing it.

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

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

A mutating, open-world tool with no output schema; the description compensates by covering permissions, side effects (owner email), response fields, auth mechanics, and the reversibility path via fastero_unpublish_widget_api. Nothing material needed to call it correctly is missing.

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

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

Schema description coverage is 100% and both parameters are already documented, including the widget-type constraint and the fastero_list_projects pointer for projectId. The description repeats the widget-type rule but adds no new parameter-level meaning, so baseline 3 applies.

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

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

States a specific verb and resource ('Publish a widget's rows as a private web address') plus the key scope qualifier ('read-only, without the database password'). It explicitly distinguishes itself from fastero_share_dashboard and fastero_unpublish_widget_api, so an agent can route correctly without opening either schema.

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

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

Gives the use case (a script or service needing the numbers outside Fastero), names the alternative and the condition selecting it (fastero_share_dashboard for people to look at), and states eligibility rules: only query, spreadsheet or notebook-cell widgets, and already-published ones are refused. Also names who may call it (owners, admins, editors).

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