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

Annotations already declare readOnlyHint=false, destructiveHint=false and openWorldHint=true. The description adds a genuinely new behavioral fact the annotations cannot express: the write is gated behind the HERO_ALLOW_WRITES environment flag. It still says nothing about failure modes or return behavior.

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

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

Three sentences, zero filler, with the what and the example front-loaded before the prerequisite and discovery steps. Every sentence carries information the 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?

For an open-world mutation with a nested passthrough object and no output schema, the definition covers purpose, prerequisites and argument discovery. Only error/permission-failure behavior is unaddressed, 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?

The schema 'documents' both params but only nominally: `arguments` is an open object whose real field names are unknown, and the schema offers no help. The description compensates by directing the agent to hero_schema for the exact argument names, which is the only way to fill the passthrough correctly.

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 ('Add an entry to a project's logbook in HERO') and grounds it with concrete examples ('a call note or site-visit summary'). No sibling tool in the list touches logbook entries, so the agent can route to it unambiguously.

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 prerequisite ('Requires HERO_ALLOW_WRITES=true') and a discovery workflow: call hero_schema and inspect the add_logbook_entry mutation before passing arguments. It does not state when to prefer this over hero_graphql directly, so it stops short of full 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?

Annotations already declare write (readOnlyHint=false), non-destructive, and open-world. The description adds genuinely useful behavior beyond that: email-based customer de-duplication, the HERO_ALLOW_WRITES=true prerequisite, and a confirm-before-call rule. It stops short of describing the dedup-match outcome or error handling, keeping it below a 5.

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

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

Four short sentences, front-loaded with purpose and then escalating to prerequisites and the confirmation guardrail. No filler; every sentence carries distinct operational value.

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

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

For a 7-parameter nested create tool with no output schema, the description covers purpose, required inputs, the key side effect (dedup), the auth flag, and a safety step. It leaves minor gaps around what happens when a customer already exists or how errors surface, but is otherwise complete.

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

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

Schema coverage is 57%, so the schema documents roughly half the parameters including enum values and nested objects. The description only restates that email and ZIP code are required (already in the schema) and adds no field-level meaning, so it neither compensates for nor exploits the coverage gap. 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 ('Create') plus resource ('new customer enquiry/project in HERO') and names the underlying Lead API. Since every sibling is a read/list tool, an agent can immediately tell this is the creation path 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 concrete activation contexts (phone call, email, website form) and a procedural guardrail ('Always confirm the details with the user before calling'). It doesn't name alternatives or when-not-to-use, but there is no competing create tool among the siblings, so 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 safety profile (readOnlyHint=true, openWorldHint=true), so the bar is lower. The description usefully adds payload-level context - documents include quotes/invoices with PDF links and the project logbook/history - which tells the agent what a call actually yields, though it says nothing about behavior on invalid ids or permission 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?

A single dense sentence, front-loaded with the action and resource and padded with nothing. Every clause contributes enumerable 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?

With no output schema, the description carries the burden of describing returns, and it does list the major fields, so an agent knows what to expect. It stops short of noting failure behavior for unknown ids or how multi-id results are keyed, which a batch getter would ideally state.

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% for the single 'ids' parameter. The description's 'one or more projects by id' only restates the array/batch semantics already present in 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?

The description gives a specific verb ('Get full details') and resource ('projects by id'), then enumerates the returned fields (customer, contact, site address, status, documents, logbook). This clearly separates it from list-style siblings, but it never names an alternative such as hero_list_projects, so sibling differentiation is only implied.

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: you call this when you already have project ids and want the complete record instead of a list. There is no explicit when-to-use/when-not or mention of an alternative tool, so the agent must infer the selection logic.

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 carry openWorldHint, so the description carries the safety burden and does so well: it discloses that the tool is read-only by default but can write when the server was started with HERO_ALLOW_WRITES=true — a conditional mutation capability the annotations never declare. It stops short of error semantics, rate limits, or query-complexity constraints, 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?

Three short clauses, purpose front-loaded, then the write-gating caveat, then the discovery prerequisite. Zero filler; every sentence changes how an agent would call the tool.

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

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

For an open-world raw-query tool with no output schema, the description covers purpose, safety gating, and the prerequisite discovery step, which is the bulk of what matters. It is slightly incomplete on response shape and failure behavior for arbitrary GraphQL, but nothing critical to correct invocation is missing.

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

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

Schema coverage is only 50%: 'query' has a description ('GraphQL document.') but 'variables' is entirely undocumented in both schema and description. The description adds no parameter meaning at all — no guidance on variable binding, query formatting, or depth limits — so at this coverage level it fails to compensate for the gap.

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

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

States a specific verb+resource ('Run a custom GraphQL query against HERO') and immediately positions it as the catch-all fallback 'for anything the other tools don't cover.' This lets an agent distinguish it from the concrete siblings (hero_list_customers, hero_get_project, etc.) without reading 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 says when to reach for it (only when no dedicated tool covers the need) and names the prerequisite alternative 'hero_schema' for field discovery. Both the usage condition and the preparatory step are stated rather than inferred.

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 openWorldHint=true, so the safety profile is covered. The description adds one genuinely useful trait — fields are auto-selected from the HERO schema, implying a variable return shape — but says nothing about rate limits, page sizes, or result counts for a tool explicitly designed around paging.

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 action and resource, then constraints. No filler, though the schema pointer is repeated from the schema description itself.

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 read-only list tool with full schema coverage and no output schema; the note that fields are auto-selected from the HERO schema partially compensates for the missing return definition. Pagination and filtering behaviors are adequately covered for correct invocation.

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

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

Schema coverage is 100%, so all three parameters are documented in the schema itself (including the instruction to call hero_schema first). The description restates the `filters` behavior already present in the schema rather than adding new syntax or format detail, 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 (List) and resource (calendar events/appointments from HERO), naming the native term 'Termine' for disambiguation. It is clearly separable from siblings like hero_list_customers or hero_list_documents by resource, though it makes no explicit contrast statement.

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 guidance on how to filter ('Pass date filters via `filters`') and points to hero_schema, which implies the right usage context. It does not say when this tool is preferable to hero_graphql or how results relate to other hero_list_* calls.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so safety is covered. The description adds that results come back as a page and enumerates the returned fields. It says nothing about rate limits, auth, or result-count limits, which is a modest gap for an open-world listing 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?

Three tight sentences with the core purpose front-loaded, the search behavior second, and the return shape last. The return-field list partially overlaps the fields already named in the search sentence, costing a little density but not clarity.

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

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

For a parameterless read-only list tool with annotations present and no output schema, the description covers purpose, filtering, and the returned field set, which is what an agent needs. It omits any note on page size or how to page beyond offset, 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 baseline is 3, but the description adds meaning by naming the exact fields `search` matches on (name, company, email, phone, address), which the schema only calls a generic 'case-insensitive text filter'. It does not extend meaning for `category`, `offset`, or `filters`, so it does not reach 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 and resource ('List contacts from HERO') and clarifies the default category ('customers by default'), which separates it from hero_list_projects, hero_list_documents, and the other list siblings. It does not explicitly name which sibling to use for other contact categories, so it stops 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?

It explains how to narrow results ('Use `search` to filter the returned page') but gives no when-to-use guidance versus hero_graphql for arbitrary queries, nor when to prefer hero_list_customers over hero_list_projects-adjacent listing tools. Usage is implied rather than 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 already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds the returned field set, which is genuine extra context, but says nothing about pagination behavior, result volume, or auth/rate-limit characteristics. With annotations carrying the behavioral load, this is an appropriate 3.

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 filler, front-loaded with the resource and its scope before the optional filtering tip. Every clause carries information an agent can act 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?

There is no output schema, and the description compensates by listing the returned fields; pagination is covered by the offset schema description, and the nested filters object points the agent at hero_schema. The only gap is the absence of any statement about result size or ordering, which is minor for a read-only 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 description coverage is 100%, so the baseline would be 3, but the description adds meaning the schema lacks: the schema only says search is 'case-insensitive text filter applied to the results', while the description clarifies what is searchable (document type names). It also implicitly signals that filters go through the GraphQL passthrough documented for the filters param.

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) plus the exact resource (customer documents) and enumerates the document kinds (quotes/Angebote, invoices/Rechnungen, order confirmations), which cleanly separates it from siblings like hero_list_customers and hero_list_projects. It also names the fields returned (number, type, net value, VAT, status, PDF link), so an agent knows what it gets 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?

The only guidance is 'Use `search` to filter, e.g. by document type name', which is parameter-usage advice rather than when-to-use-this-vs-alternatives. No exclusions or routing to sibling tools (e.g. when to prefer hero_graphql or hero_schema) are given; usage is implied by the tool name.

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 openWorldHint=true, so the safety profile is covered. The description adds one genuine behavioral fact beyond that: fields are auto-selected from the HERO schema, so the agent cannot request specific fields. It says nothing about pagination limits, result caps, or what the auto-selected field set contains.

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 verb+resource is front-loaded ahead of the example use cases. Every clause carries information the agent can act 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 read-only list tool with a fully documented schema and safety annotations, what remains is the return shape: there is no output schema, and the description only says fields are auto-selected without indicating what the agent can expect back. Adequate, but the output ambiguity is left 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 offset, search and filters are already fully documented in the schema, including the pointer to hero_schema for GraphQL arguments. The description adds no parameter-level detail beyond the schema, which is the correct baseline 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?

States a specific verb (List) and resource (products/articles from the HERO product catalogue), and adds a use case (looking up prices or article numbers). It reads as distinct from siblings like hero_list_customers or hero_list_documents, though it stops short of explicitly contrasting with them or with hero_graphql.

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 example use cases ('look up prices or article numbers') imply when to reach for this tool, and the filters param steers the agent to hero_schema for advanced queries. There is no explicit when-not guidance nor a named alternative for ad-hoc GraphQL needs (e.g. hero_graphql), so usage is only implied.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds the returned field set, which is genuinely useful context, but says nothing about paging behavior, result volume, or ordering — and it doesn't need to repeat the read-only fact.

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

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

Two tight sentences, zero filler, with the identity of the tool and its returned fields front-loaded ahead of the filtering tip. 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?

With no output schema, the description usefully enumerates returned fields, and annotations cover the safety profile. Minor gaps remain — paging/result-size behavior is only implied through the schema's offset parameter — but 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 the baseline is 3; the description earns a bump by giving concrete examples of what `search` matches (customer name, city, status) beyond the schema's generic 'case-insensitive text filter'. It adds nothing for `offset` or the pass-through `filters` object, which the schema already documents.

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 projects') and enumerates the fields returned (project number, trade/measure, customer, site address, status), which lets an agent distinguish it from the single-record hero_get_project. It does not explicitly name a sibling to differentiate against, so it falls short of a 5.

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

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

The second sentence gives concrete guidance on using `search` to filter by customer name, city, status, which is useful, but there is no statement of when to prefer this over hero_get_project, hero_graphql, or hero_list_customers. 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?

Annotations already declare readOnlyHint=true and openWorldHint=true, so safety is covered. The description adds genuinely useful behavioral detail beyond them: no-argument calls list all queries and mutations with their arguments, while a type argument lists that type's fields. It does not mention rate limits or return size, but for a read-only introspection tool this is substantial added 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?

Three short sentences, each earning its place: purpose, default behavior, parameterized behavior, and routing guidance. Front-loaded with the core action and free of 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-optional-parameter, read-only introspection tool with no output schema, the description covers both invocation modes and what each returns, plus when to prefer it over its sibling. 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 description coverage is 100% and the schema already documents the 'type' parameter with an example ('Contact'). The description adds only a use-case hint (inspect the return type of calendar_events) and notes the parameter is optional, so 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 ('Explore the HERO GraphQL schema') and immediately explains the two distinct operating modes, so an agent knows exactly what the tool produces. It explicitly positions itself against the sibling hero_graphql, making it distinguishable 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?

Gives a concrete routing rule: 'Use this before hero_graphql or when you need filter arguments.' That names both the alternative tool and the trigger condition for choosing this one, leaving little to inference.

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