Quadratic

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

The description richly discloses behavior beyond annotations: login returns a URL, confirm_login is idempotent and can be polled repeatedly, set_token directly sets a JWT, and logout clears saved auth. It also explains the nuance that some clients use new sessions per request, which is critical for effective use. This does not contradict the annotations (destructiveHint=true aligns with logout; idempotentHint=false is clarified per-action).

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

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

The description is well-structured with a short opening sentence followed by a bulleted list of actions. Each bullet is concise, information-dense, and directly relevant. No fluff or repetition; every sentence contributes to understanding.

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

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

Given the tool's complexity (multiple actions, async polling, session nuances) and the generic schema, the description is remarkably complete. It covers all actions, their parameters, step-by-step flow, idempotent behavior, and error recovery. No output schema exists, but the description clarifies expected inputs and key outputs like the login URL.

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

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

The input schema only provides generic 'action' and 'params' fields. The description compensates fully by specifying the arguments for each action: login() takes no params, confirm_login(device_code) requires a device code, set_token(token, email?) takes a token and optional email, and logout() takes none. This is essential guidance that the schema does not provide.

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 'Authenticate the MCP session with Quadratic'—a specific verb and resource. It then enumerates four distinct actions (login, confirm_login, set_token, logout), making the tool's purpose unambiguous and clearly distinct from sibling file/data 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?

Explicit usage guidance is provided for each action: use login for OAuth device flow, confirm_login to complete/poll authorization, set_token when OAuth is unavailable, and logout to clear auth. It also instructs when to re-call confirm_login (on 'Not authenticated' errors) due to session differences, offering concrete when-to-use and alternative guidance.

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

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

Beyond the readOnlyHint and idempotentHint annotations, the description discloses the required open-file prerequisite, pagination defaults and limits, the next_from null condition, and the block path/hash model. These are substantial behavioral details 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?

The description is front-loaded with the read-only scope and prerequisite, then organized into a scannable action list. The detail is proportionate to a multi-action tool and no sentence 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 explains the shape of each action's return values, including block paths, hashes, pagination fields, and search snippets. It gives enough context for an agent to invoke and interpret the tool without further documentation.

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

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

Although the schema has full description coverage, it only generically describes action and params. The description compensates by documenting each action name and its parameters, including defaults, formats, pagination arguments, and search options.

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: read-only queries on the open DOC document. It distinguishes itself from doc_write by noting that no data is modified and from files_read by scoping to files whose kind is DOC.

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

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

It gives clear prerequisites (open the document first with files_write(open_file)) and recommends doc_outline as the starting point for long documents. It lacks an explicit statement naming doc_write as the alternative for modifications, though the read-only framing implies 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 past the annotations by disclosing that edits apply live to concurrent viewers, that edit access is required, that stale block hashes cause a refusal with no partial change, and that responses carry the written paths/hashes plus a saved:false signal that still means applied. The batch atomicity and 100-operation cap are non-obvious traits an agent must know 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-loaded with the key constraints, then bulleted actions, with no filler sentences. It is dense and long, but each sentence carries required behavior (hash staleness, qd-node placeholders, saved:false). Minor cost: the read_doc reference conflicts with the actual sibling name doc_read, which briefly blurs the pointer.

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, non-idempotent, multi-action mutation tool with no output schema, the description covers prerequisites, failure modes, return payload, and content-format preservation. Nothing an agent needs in order to call it correctly appears to be missing.

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

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

The schema only defines a bare action string and an opaque params blob, so the description carries the real load: it documents every action's signature, the position enum for insert_blocks, the {path, hash} shape for replace_blocks/delete_blocks, the find_replace flags, and the batch operations envelope. This is meaning 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 ('Edits to the open document') and immediately scopes it to files whose kind is DOC, which separates it from slide_write, files_write and write_data. The action list makes the concrete operations available 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?

Explicit sequencing is given: read with doc_read first, then pass block paths and hashes because paths shift. It also names the routing alternative by implication (doc_read) and explains when to use batch versus individual actions (up to 100 edits as one all-or-nothing change).

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

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

Annotations already declare readOnlyHint, idempotentHint and openWorldHint, so the safety profile is covered. The description adds useful context — 'No data is modified' and 'Requires authentication' — but says nothing about pagination or result caps on list_files, how an inaccessible or non-existent file_id is reported, or what the response looks like. With annotations carrying the safety burden, this is adequate but not rich.

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

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

It is front-loaded with a one-line scope statement, then a kind taxonomy, then a bulleted action list — easy to scan and appropriately sized for a two-action tool. There is minor duplication: 'No data is modified' restates readOnlyHint, and the kind-to-tool mapping appears twice in slightly different form.

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

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

For a read-only metadata tool with no output schema, the description covers the scope, both actions, the kind filter and the authentication requirement, which is enough to invoke it correctly. The remaining gap is insufficient disclosure of return details — the description mentions kind and web URL for get_file_info but not what list_files returns per entry or whether results are limited.

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

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

The schema is only a generic action/params envelope with an untyped params object, so the description is the sole source of parameter meaning. It supplies the actual accepted action strings and the shape of their arguments, including the concrete kinds values ('["GRID"]', '["DOC"]', '["SLIDE"]') and the semantics of file_id. Without this text an agent could not construct a valid call.

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 ('Read-only file metadata operations on Quadratic files') and enumerates the two concrete actions, list_files and get_file_info, with their arguments. It also maps file kinds to the sibling tools that edit them (GRID→read_data/write_data, DOC→doc_read/doc_write, SLIDE→slide_read/slide_write), so an agent can separate this metadata tool from the content-editing 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?

It clearly frames the context: use this to discover or inspect file metadata, and use the per-kind tools to read or write content. The kinds filter is explained as a way to limit listing to GRID, DOC or SLIDE. What's missing is an explicit 'when not to use' statement — e.g. that this returns metadata only and never content, so an agent must chain to read_data/doc_read/slide_read after resolving an id.

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 substantial context beyond the annotations: authentication is required, open state persists per user across MCP sessions with last-open-wins semantics, and callers using per-request sessions need not re-open after auth(confirm_login). It also documents return values (kind, web URL, UUID) and the team defaulting behavior. It does not explain why destructiveHint=true (what closing a session loses or whether create is reversible), leaving one annotation unexplained.

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 summary sentence followed by per-action bullets, which is well suited to a multiplexed tool. Each bullet carries actionable information, though the open_file bullet is dense and could be split so the sibling routing is easier to scan.

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-action multiplexed tool with a generic envelope schema and no output schema, the description covers prerequisites, defaults, return values, session persistence and auth. The only minor omission is what close_file returns, which an agent is unlikely to 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?

The input schema is only a generic action/params envelope, so the description carries essentially all parameter meaning: it names file_id, file_name, team_uuid and kind per action, states kind defaults to GRID with DOC/SLIDE alternatives, and explains that an omitted team_uuid falls back to the user's first team. This is meaning the schema alone cannot provide.

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 opening sentence names a specific domain (file management) and enumerates the three concrete actions: create a file, open a file to start an editing session, close a session. It is clearly different from the sibling files_read. It loses a point because bundling a non-mutating session-open under a tool named 'files_write' slightly blurs what the tool really is.

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

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

Strong routing: after open_file it explicitly tells the agent to use read_data/write_data for spreadsheets, doc_read/doc_write for documents and slide_read/slide_write for presentations, and it states the prerequisite that a file must be opened before editing. It does not explicitly state when to prefer files_write over files_read, but the read/write split is obvious from the action list.

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

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

Beyond the readOnlyHint/idempotentHint annotations, the description adds 'Safe to auto-approve', explains batch per-entry failure without short-circuiting, pagination for large results, team_uuid fallback behavior for single-team users, and secret substitution via {{SECRET_NAME}}. These are meaningful operational disclosures.

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

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

Extremely long but well-organized into sections (general, special actions, action reference, batch). Each action entry is concise and front-loaded with behavior. Some repetition (e.g., team_uuid optional note) but every sentence adds necessary operational detail.

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

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

Given the tool is a dispatcher for 18+ sub-actions with no output schema, the description is remarkably complete: it covers return shapes (e.g., list_connections returns uuid/name/type, export_pdf returns mime_type/size_bytes/data_base64), pagination, error handling, prerequisites, and optional parameter behavior. Nothing critical 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 only has 'action' and 'params' with generic descriptions. The description provides full parameter semantics for every sub-action, including A1 notation selection formats, optional parameters with defaults, regex examples, output formats for export_pdf, and connection types. This compensates entirely for schema sparsity.

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?

Description states 'Read-only queries on the open spreadsheet' with explicit 'No data is modified', clearly distinguishing from write_data sibling. It enumerates a full action reference, making the dispatcher role unambiguous. The verb+resource pairing is specific and actionable.

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

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

Provides explicit when-to-use guidance: 'Use before creating/moving tables or code to avoid spill errors', 'Call this BEFORE get_database_schemas or set_sql_code_cell_value', 'Preferred over get_cell_data for most reads', and 'Do NOT use for formula cells'. Also includes call format and special batch/context usage.

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

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

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint=false, so "No data is modified. Safe to auto-approve" largely restates them. The description earns credit for disclosing behavior the annotations cannot: EMU unit semantics (914400 per inch, 12700 per point), pagination defaults and the 500 max, and that next_from is null on the last page.

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 safety and prerequisite statements, then a scannable bulleted action list where each line does real work. It is long, but the density is justified for a six-action dispatcher; only the early repeated safety line could be trimmed against the annotations.

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

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

For a polymorphic action dispatcher with no output schema, it is largely complete: prerequisites, unit conventions, pagination contract, and per-action payload summaries (shape types sp/pic/cxnSp/tbl, notes, comments, theme, footer). It stops short of describing error or failure behavior when no presentation is open.

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

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

The schema is a bare skeleton — action is just a string listing four names and params has no structure at all — so the description carries essentially all parameter meaning. It documents per-action parameters with defaults and ranges (from 0, limit 50/500, include_resolved, format markdown vs json) and clarifies that shape geometry is in EMU unless units is "in" or "pt".

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

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

The description names a specific verb family and resource: "Read-only queries on the open presentation (a file whose kind is SLIDE)," and explicitly contrasts with slide_write ("slide_write addresses edits by them"). The six actions are enumerated with one-line scopes, so an agent can distinguish this from slide_write, doc_read, and files_read without opening the schema.

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

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

It supplies a prerequisite ("Open the presentation first with files_write(open_file)") and a routing hint ("Start here" on deck_outline), plus a pointer to context() for the full guide. It does not state when to prefer files_read or doc_read over this tool, so the sibling routing is only partially 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?

Goes well past the annotations: it discloses that edits apply live to anyone viewing, that a mutation returns what it wrote plus 'saved: false' when unconfirmed, that null clears background/transition/fill/descr/crop, and that batch is all-or-nothing with ids from earlier operations unavailable to later ones. These are exactly the mutation semantics an agent cannot infer from destructiveHint=true alone.

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, prerequisites, and global conventions (Markdown, EMU units, layout names) before the action catalog, so an agent can stop reading early if it only needs the general rules. It is long, but the length is justified by 28 actions with no schema documentation; only minor redundancy in repeated list/dict syntax keeps it from a 5.

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

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

For a 28-action polymorphic tool with no output schema, the description covers every action listed in the schema's action field and explains the return shape ('Every edit returns what it wrote (new ids, placeholder shapes, z-order)'), which substitutes for the missing output schema. Errors and live-coauthoring conflicts are the only unaddressed areas.

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

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

The schema is a two-field dispatcher whose 'params' is an untyped object, so the description carries the entire burden and does so thoroughly: per-action parameter names, defaults ('obj' is the default layout, omitted xfrm centers the shape), enum values (geometry, alignment, table styles, 'front'/'back'/'forward'/'backward'), null-clearing behavior, and Markdown/ProseMirror plus EMU/in/pt content conventions.

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 ('Edits to the open presentation') and narrows scope to 'a file whose kind is SLIDE', which separates it from doc_write, while slide_read is named as the read counterpart. The action list that follows makes the edit surface concrete rather than abstract.

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

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

Explicitly states the prerequisite workflow ('Read the presentation first (slide_read deck_outline or read_deck) to get slide and shape ids') and the access requirement ('Requires edit access'), so an agent knows when it is eligible to call it. It also implies that batch is the route for many edits at once, but never states when *not* to use this tool relative to doc_write or when a single live edit is preferable to a batch.

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 the description aligns with that. It adds substantial behavioral context beyond the annotations: numeric/boolean/null coercion to strings, batch short-circuiting, spill error avoidance for code cells, the requirement to call get_database_schemas before SQL, chart float behavior, pivot table read-only cells, and many other operational details. It also notes that set_code_cell_value, set_formula_cell_value, and set_sql_code_cell_value run automatically so rerun_code should not be called after them. This goes far beyond the annotation.

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 extremely long, but it is necessary given the tool's breadth (40+ actions). It is well-structured with clear headings (Cell Data, Code, Import, Formatting, Sheets, Tables, etc.), action signatures, and inline notes. It front-loads the purpose and call format. While not concise in length, every sentence serves a purpose and the structure improves scannability. It earns a 4 rather than 5 only because some individual action notes are verbose and could be tightened, but overall it is appropriate for the complexity.

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

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

For a tool with this many actions and no output schema, the description is remarkably complete. It covers all action signatures, parameter details, usage heuristics, edge cases (e.g., merged cells, spill errors, data table spacing), return values where relevant (e.g., add_chart returns chart_id), and even special behaviors like the context action for deeper docs. It gives the agent everything needed to call any action correctly without external reference. There are no significant gaps for an agent to misuse the tool.

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

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

The input schema only defines 'action' and a generic 'params' object with no per-action schema. The description carries the entire burden of parameter documentation, and it does so comprehensively: each action is listed with its exact parameter names, types, defaults, and usage notes (e.g., 'top_left_position: single cell in A1 notation', 'color: hex string', 'line: line1/line2/line3', 'size: auto/default/pixels'). Even edge cases and constraints are explained (e.g., 'sheet names: unique, max 31 chars'). This fully compensates for the schema's lack of detail.

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

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

The first sentence clearly states 'Write operations on the open spreadsheet', immediately establishing the tool's scope and distinguishing it from read tools like read_data. It then enumerates all supported actions, leaving no ambiguity about what the tool does. The description is explicit about the verb (write) and the resource (spreadsheet).

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

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

The description provides extensive when-to-use guidance both at the tool level (write operations vs. read operations implied by sibling names) and at the action level. For example, it explicitly says 'Prefer this over add_data_table' for set_cell_values, 'only use code when functionality is not available in formulas', and 'Use STOCKHISTORY formula for basic historical stock prices'. It also gives exclusions like 'Don't use for formulas or code' for certain actions, and explains when to use batch and context. This fully equips an agent to select the right action.

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