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

No annotations provided, so description carries full burden. Only states it returns a count; does not disclose return format (e.g., integer), side effects, permissions, or limitations like maximum count.

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?

Single sentence that is front-loaded and to the point. No wasted words.

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

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

Lacks output schema and annotations; does not clarify return format or possible constraints. Adequate for a simple count but could be more complete.

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

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

Schema covers both parameters with descriptions (100% coverage). Description adds cross-reference to introspect_filters for filter shape, which is helpful beyond 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?

Describes exactly what the tool does: returns total number of records for a model, with optional filtering. Clearly distinct from sibling tools like get_record (single record) or query_records (list).

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

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

No explicit guidance on when to use this tool versus alternatives (e.g., query_records for full records, get_record for single record). Agent must infer usage from description alone.

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 no annotations, the description carries the full disclosure burden and does substantial work: it reveals the side effect (writes a file to the local filesystem), that pagination is handled automatically, that redaction settings affect output, and what the result contains (path, row count, columns, preview). It omits permission requirements and overwrite/error behavior, so it is strong but not complete.

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 tight sentences with the primary purpose and the sibling comparison front-loaded, then behavior, then return shape. Nothing is redundant, though 'Redaction settings apply.' is terse to the point of being slightly cryptic about what is being redacted.

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 7-parameter bulk-export tool with no output schema and no annotations, the description covers purpose, pagination, side effects and return contents, which is most of what an agent needs. Remaining gaps, such as overwrite behavior and auth requirements, are secondary but not trivial for a tool that writes files.

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

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

Schema description coverage is 100%, so the schema already documents model, fields, filter, format, filename, max_records and sort with examples. The description adds no parameter-level detail beyond the format options (already an enum) and a vague note that redaction settings apply. 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 (export) and resource (records) plus the output form (CSV/JSON file on this machine), which is concrete and actionable. It also differentiates itself from the sibling query_records by citing the 50-record threshold, so an agent can route between them 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 use context (bulk export for analysis or sharing) and explicitly names the alternative, query_records, with the condition that selects this tool (result sets beyond 50). It does not state any explicit when-not-to-use case (e.g. single-record lookups belong in get_record), so it falls just short of the top band.

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 no annotations provided, the description carries the full behavioral burden. 'Get' implies a read, but nothing is said about permissions/auth requirements, error behavior for a missing or invalid ID, or whether the returned shape depends on the fields selection. This is thin for an unannotated 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?

Two short sentences with the purpose front-loaded and no filler. The second sentence is largely redundant with the schema, which keeps it just short of a 5.

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

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

For a simple 3-parameter read tool with full schema coverage and no output schema, the description is minimally adequate. It omits error/not-found behavior and any hint that the fields selection governs the response shape, which would matter for an agent calling it cold.

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 baseline is 3; the schema already documents 'model' (camelCase example) and 'fields' (GraphQL selection syntax) thoroughly. The description only restates that these three inputs exist and adds no syntax or format detail 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?

The description states a specific verb and resource with scope ('Get a single Gadget record by ID'), which clearly separates it from list-style siblings. However, it never names or contrasts with the obvious alternatives (query_records, run_graphql), so the agent must infer the boundary itself.

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 ('Specify the model name, record ID, and fields to return') is a restatement of the input parameters, not usage guidance. There is no statement of when to prefer this over query_records or run_graphql, nor any prerequisite or exclusion.

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?

No annotations, but description transparently reveals the tool's output (all models with fields/types) and scope (single call). A simple read operation, well explained.

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

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

Two concise sentences, front-loaded with purpose followed by usage guidance. No extraneous words.

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

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

For a zero-parameter tool returning schema overview, description fully covers purpose and usage. No missing details.

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?

No parameters exist, so description adds no param info. Baseline 4 per guidelines for zero-param tools.

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 clearly states 'Return all models with their fields and types in a single call', specifying verb, resource, and scope. It distinguishes from siblings like 'introspect_model' (specific model) and 'list_models' (names only).

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?

Text advises using this for 'broad understanding before diving into specific models', providing context and implying alternatives. Explicit when-not or named alternatives would push to 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?

With no annotations, the description carries the full burden and does disclose a genuinely non-obvious behavioral trait: accuracy is field-type dependent, non-enum fields are computed by scanning up to max_records, and the result self-reports whether it is exact. It still omits permissions, cost/latency implications of scanning, and truncation behavior, but the key semantic caveat is surfaced.

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 purpose followed by the accuracy caveat; no filler. Dense but efficient, and each clause carries information the schema does not.

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

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

For a 5-parameter read tool with no output schema and no annotations, the description covers the essential correctness caveat (exact vs. scanned) and ties it to the scan limit. It is not fully complete, since the shape of the returned grouped counts and behavior under filters are unstated, but nothing critical 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, but the description adds real meaning by linking max_records to the non-enum scanning path and framing field as an enum/boolean vs. scalar distinction. It also implies top is only relevant for non-enum fields, consistent with the schema notes.

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 (count), resource (records), and a precise grouping semantic ('grouped by a field's value') with concrete examples (orders by financialStatus, products by vendor). It does not, however, distinguish itself from the sibling count_records, leaving the agent to infer the boundary.

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 through the exactness note: enum/boolean fields are exact, other fields are scan-based, which tells the agent which field types to prefer. But there is no explicit when-to-use guidance and no mention of count_records as the alternative for ungrouped totals, so tool selection against the closest sibling 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?

No annotations are provided, so the description carries the burden. It implies a safe, read-only listing and discloses that arguments are included, but says nothing about auth requirements, rate limits, or whether results are paginated/complete. Adequate but thin for a tool with zero annotation coverage.

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

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

Two sentences, zero waste. The purpose is front-loaded and the consumer tools are named second, so the agent gets the what before the why.

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 convey return content; 'including their arguments' tells the agent it will get action names plus argument shapes, which is the key information for a discovery tool. It does not describe the response structure in any detail, leaving a modest 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?

The tool takes no input parameters and the schema is a bare empty object, so the baseline is 4. There is no input semantics to clarify; the description's param-adjacent statement about returned arguments belongs to output, not input.

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 ('List all actions (mutations) available in this Gadget app') and adds the scope 'including their arguments', which separates it from model-listing siblings like list_models and introspect_model. It never names those siblings directly, so differentiation is implied rather than explicit, which keeps it just short of a 5.

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

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

Gives clear usage context: 'Use this to find action names and argument shapes for run_action, create_record, and update_record.' It routes the agent toward the write tools that consume this output. It does not state when NOT to use it (e.g., versus introspect_model for field discovery), so it stops at 4.

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?

No annotations provided, so description carries full burden. It accurately describes a read-only introspection tool without side effects, but could be improved by noting any authentication requirements or potential performance impact.

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

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

Two sentences, no filler. Every sentence provides essential information: what it does and how to use 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?

Given the simple single-parameter input and no output schema, the description adequately covers purpose and usage. It could briefly mention what the output contains (e.g., list of fields with types), but it's still sufficient for an introspection 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%, so baseline is 3. The description does not add extra meaning beyond the schema's 'Model name in singular camelCase' example; it simply restates the parameter role.

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

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

The description clearly states the tool shows all available filter fields and their types for a Gadget model, using specific verb 'show' and resource. It distinguishes from siblings like query_records and count_records by explicitly linking to filter argument construction.

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

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

The description explicitly states to use this tool for constructing valid filter arguments for query_records and count_records, providing clear context. However, it does not mention when not to use it or alternatives like introspect_model.

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?

No annotations provided, so description carries full burden. Only states listing action with no disclosure of read-only nature, error handling, or performance implications. Minimal behavioral context.

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

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

Two sentences, front-loaded with purpose and usage. No redundant or missing words. Highly efficient.

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

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

Simple tool with one parameter and no output schema. Description covers purpose and usage. Could mention return format but not essential. Adequate for the context.

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

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

Schema coverage is 100% with clear parameter description. The tool description adds little beyond stating 'for a Gadget model', which is already implicit. 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?

Clearly states 'List all fields and their types for a Gadget model' with a specific verb and resource. Distinct from sibling tools like list_models, introspect_actions, etc.

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 recommends running this tool 'first when you're unsure what fields exist on a model.' Provides a usage context but does not name alternatives or exclusions explicitly.

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

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

The description discloses the method (GraphQL introspection) and implies a read-only operation. With no annotations, it provides sufficient behavioral context for a simple list operation.

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

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

A single, well-structured sentence that is front-loaded and contains no unnecessary 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 zero-parameter tool with no output schema, the description is complete. It explains the purpose and method, and there is no missing context given the tool's simplicity.

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

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

No parameters, so baseline is 4. The description does not need to add parameter meaning, and schema coverage is 100% (none).

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

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

The description clearly states the tool lists all models (types) via GraphQL introspection. It uses a specific verb and resource, distinguishing it from sibling tools like introspect_model which focus on a single model.

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

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

No explicit guidance on when to use this tool versus alternatives. Usage is implied from the description, but exclusions or comparisons to siblings like introspect_actions are not provided.

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

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

With no annotations, the description carries the full behavioral burden. It discloses two useful defaults (all scalar fields returned when fields is omitted, cursor-based pagination) but says nothing about read-only safety, authorization requirements, result shape, or rate limits.

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

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

Two sentences, no filler, and the capability scope is front-loaded before the cross-tool pointer. Every clause 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?

Adequate for a read/query tool: capabilities, default field behavior, and the filter-discovery path are all covered, and the schema is fully documented. But with no output schema and no annotations, the description could have said more about the returned result shape and when not to use 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%, so the schema already documents every parameter with examples (sort object shape, endCursor usage, limit default/max, GraphQL field selection syntax). The description only restates the capability list and adds the introspect_filters pointer, 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 ("Query records from any Gadget model") and enumerates the supported capabilities: filtering, sorting, pagination cursors, field selection. It does not differentiate itself from siblings like get_record, count_records, or run_graphql, so the agent must infer scope from names alone.

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?

One explicit routing hint is given — "Use introspect_filters to see valid filter shapes" — which is genuinely useful. However, there is no guidance on when to prefer this over get_record (single record), count_records, export_records, or run_graphql, so usage is only partially implied.

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

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

With no annotations at all, the description carries the full burden and does meaningful work: it discloses the CLI dependency, a mandatory one-time `npx ggt login` precondition on the machine, and the default window/level. It does not describe output shape, truncation, or failure modes, but the auth prerequisite and defaults are the operationally important facts an agent 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 sentences, front-loaded with what the tool does and its scope, followed by the operational prerequisite. No filler; 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?

For a parameterless-to-invoke read tool with full schema coverage and a stated auth precondition, the description covers what an agent needs to decide and execute. The one gap is that no output schema exists, so a hint about the returned line format would have added value.

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 every parameter already has an enum or a detailed description with units/defaults/max ('default 100, max 500', '"15m", "2h", "1d", or an ISO timestamp'). The description only restates the level and window defaults, adding no syntax or semantics beyond the schema, 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+resource ('Read recent logs from the Gadget app'), names the underlying mechanism ('via the ggt CLI'), and gives the intent ('to debug errors, failed actions or webhooks'). This distinguishes it clearly from the record/model/GraphQL siblings in the toolset.

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 supplies a clear context of use (debugging errors, failed actions, webhooks) and the schema reinforces it with 'use "error" to find failures'. It stops short of naming when-not-to-use this tool or pointing to an alternative sibling, so it is clear context rather than explicit 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?

With no annotations, the description carries the full burden and does well: it discloses the key side-effect fact that 'nothing is posted automatically' and the returned artifact is a link for user review, plus a data-safety caution about API keys and customer data. It does not cover auth/permission requirements, keeping it just short of a 5.

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

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

Three tight sentences, front-loaded with the action, then usage, then the behavioral caveats. Every sentence earns its place and there is no repetition of schema content.

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 link-generating tool with no output schema, the description covers the essential facts an agent needs: what it produces, that submission is not automatic, and how to use it. Nothing material is missing given full schema coverage.

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 all five parameters (title, what_happened, steps, expected, error_output) are already documented in the schema. The description adds no further parameter guidance, 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 ('Create a pre-filled GitHub bug report link') and scopes it to gadget-mcp itself rather than the user's Gadget app. This clearly separates it from every sibling, which are all data/query 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?

Gives explicit trigger conditions: 'Use when a gadget-mcp tool misbehaves or the user asks to report a bug.' It also pre-empts a likely mis-use by clarifying that it is not for the user's own Gadget app, 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?

No annotations provided, so the description carries full burden. It clearly declares read-only behavior. While it doesn't detail error handling or rate limits, the key behavioral trait (read-only) is explicitly stated.

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

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

Two concise sentences: first defines purpose, second provides usage guidance. No redundant or extraneous information.

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

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

Given no output schema and no annotations, the description adequately covers purpose, usage, and parameter context. It doesn't detail return format, but GraphQL responses are self-explanatory. Slight gap: no mention of authentication or scope.

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

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

Schema coverage is 100% with descriptions. The description adds context beyond schema by explaining the tool is for complex, nested, or custom-filtering queries, which guides parameter use.

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

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

The description clearly states the tool executes a read-only GraphQL query against the Gadget app. It distinguishes from sibling tool query_records by noting it handles 'complex queries with nested relations or custom filtering that query_records can't express.'

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: 'Use this for complex queries...' implies when not to use (simpler queries should use query_records). The description also clarifies it is read-only.

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