ESG Hub MCP Server

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

Goes well beyond the annotations by disclosing the deferred/proposal workflow ('nothing changes immediately', returns a proposal_id, page unmodified until a curator approves) and states operational constraints: ESG_HUB_WRITE_TOKEN required and rate-limited. This is exactly the destructive-mechanics context an agent needs and does not merely restate destructiveHint=false.

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

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

Dense but front-loaded: the effect-not-immediate caveat is stated early, then usage, then per-action semantics, then auth constraints. Every sentence carries information, though the action semantics partly duplicate the schema enum and could be trimmed.

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

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

Output schema exists so return values need no explanation, yet the description usefully names proposal_id. With 3 params fully documented, auth requirements, rate limits, and the deferred-approval model all disclosed, an agent has everything needed to call this correctly and interpret the result.

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

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

Schema coverage is 100%, so the baseline is 3, and the description still adds value: server-side resolution of page_id from permalink/slug/record ID, the min-10-character reason constraint, and the meaning of each action value including the default. Minor overlap with the enum descriptions keeps it from a 5.

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

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

States a specific verb (queue for human curation) plus the resource (one ESG Hub page) and enumerates the three possible outcomes. It explicitly names the sibling it is not (tag_content) for the adjacent edit-tags case, so an agent can route correctly without opening either schema.

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

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

Gives explicit when-to-use triggers ('outdated, duplicated, or inaccurate') and an explicit alternative with its own condition ('to edit its facet tags instead use tag_content'). Nothing about selection is left to inference.

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

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

Annotations cover only the safety profile (readOnly, idempotent, closed-world), while the description adds real operational context: a single non-paginated object, seeded reference values that change only on deploy, session-level cacheability, a ~10 minute cache, per-IP rate limiting, and retry-on-5xx guidance. This is substantial disclosure beyond the annotations and nothing contradicts them.

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

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

Front-loaded with the purpose, then usage routing, then return and caching behavior. Every clause carries information, though the caching/rate-limit tail is packed densely into semicolon-separated fragments.

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 reference-lookup tool with an output schema, the description covers everything an agent needs: purpose, sequencing relative to sibling list tools, return cardinality, cache lifetime, and failure handling. Nothing material is left to inference.

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

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

The tool takes zero parameters, so the schema is empty and the baseline is 4 per the rubric. The description reinforces this ('It takes no parameters') and describes the return shape, but there are no parameter semantics to add beyond that.

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

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

Starts with a specific verb and resource ('Discover the filter vocabulary for the knowledge base') and enumerates exactly what comes back: total counts plus the section, pillar, and source-domain values with counts. It is immediately distinguishable from siblings like list_esg_pages or get_server_info, which it names.

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 antecedent guidance ('Call it before list_esg_pages or list_esg_resources so filters match real values') and routes a related need elsewhere ('for server version and health use get_server_info'). Both when-to-use and the alternative are stated, not 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 cover read-only/idempotent/closed-world, but the description adds substantial behavior beyond them: it resolves only `page` records, a resource URL yields NOT_FOUND, redirect-only records resolve to their target, unknown IDs yield NOT_FOUND, ~10-minute caching, per-IP rate limiting, and retry-on-5xx guidance. This is exactly the kind of failure-mode and operational context annotations cannot express.

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

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

Dense but front-loaded: purpose first, then usage routing, then return payload, then edge cases and operational notes. No sentence is filler; each adds a distinct fact an agent would otherwise have to discover by trial.

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?

An output schema exists, yet the description still briefly frames the return payload (body plus section, pillar, keywords, canonical URL). Combined with the ID resolution rules and rate-limit notes, nothing an agent needs to call this correctly is missing.

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

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

Schema description coverage is 100% and already lists permalink/slug/record ID, so the baseline is 3. The description adds concrete format examples ('standards/gri-101', 'page:abc123') and, importantly, the resolution semantics of the parameter — which inputs resolve and which fail — giving it value above 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?

Starts with a specific verb+resource ('Read one ESG Hub article in full') and immediately scopes the identifier forms accepted. It draws a clean line against the sibling get_related ('neighbours rather than its content'), so an agent can discriminate without opening schemas.

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

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

Explicitly states the trigger conditions — 'once search_esg, search_content, or list_esg_pages has returned an identifier' — and names the alternative tool (get_related) with the condition that selects it. Both when-to-use and when-not-to-use are covered.

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

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

Goes well beyond the readOnlyHint/openWorldHint annotations: it discloses the 15-record cap, that only `related_pages` edges exist today, that an unlinked page returns an empty group list rather than an error, that there is no pagination, ~10-minute caching, per-IP rate limiting, and retry-on-5xx behavior. This is unusually rich operational 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?

Front-loads the core behavior, then packs edge cases into tight clauses. Every sentence conveys a distinct constraint (cap, edge coverage, empty result, pagination, caching, rate limits) with no filler.

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

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

With an output schema present, return values need not be explained, and the description nonetheless covers result shape, cap, empty-case semantics, and operational limits. An agent has everything needed to call this correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds genuinely new meaning: the accepted `record_id` forms (`page:` ID or permalink) and the `edge_type` default of 'all', which the schema does not state. It does not enumerate valid edge type values, which stays as a residual 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 and scope: 'Traverse the ESG Hub knowledge graph one hop from a page and return every connected record grouped by edge type.' It explicitly distinguishes itself from get_esg_page, so an agent can tell the two apart without opening a schema.

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

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

Gives explicit sequencing ('use it after get_esg_page when you need neighbouring concepts') and names the alternative with its selecting condition ('to read a page's own content use get_esg_page'). Nothing is left to inference.

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

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

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint=false, so safety is covered. The description adds behavior the annotations cannot express: exactly one liveness round-trip, and the failure contract — it never errors on an unreachable API but returns healthy=false instead. That non-obvious error semantics is the kind of disclosure that changes how an agent handles the response.

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

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

Three sentences, front-loaded with the primary action, then the return shape, then the failure contract, then the sibling routing. No filler and every clause carries information an agent needs.

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

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

With zero params, a rich output schema, and full anisotropy of annotations, the description covers everything material: purpose, ordering, return fields, error behavior, and alternative tool. Nothing needed to call it correctly is missing.

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

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

Zero parameters, so per the rubric the baseline is 4. The description does useful work by enumerating the returned metadata fields (name, version, API base, tool_count, healthy), but there are no parameters whose semantics could be enriched.

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 (confirm the ESG Hub MCP server is reachable; return version and API base) and immediately names the sibling to use instead for other data: 'For sections, pillars, source domains, or totals use get_esg_metadata.' An agent can distinguish it from all 14 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 gives explicit ordering guidance ('Use this first') plus a clear routing rule away from itself to get_esg_metadata for richer ESG data. Both the when-to-use and the when-to-use-something-else cases are covered.

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

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

Beyond the readOnly/idempotent annotations, it discloses exact (case-insensitive) matching with no fuzzy/partial semantics, guarantees a single record rather than a list, specifies NOT_FOUND for unknown identifiers, and adds caching (~10 min), per-IP rate limiting, and 5xx retry guidance. These are operational traits an agent cannot derive from the annotations.

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

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

Front-loads the core action, then alternates, then behavioral caveats, then operational notes. Every clause carries distinct information; nothing is restated from annotations or schema.

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

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

An output schema exists, yet the description still orients the agent by naming the key fields (definition as authoritative, facets for classification). Identifier formats, failure mode, matching semantics, and rate-limit behavior are all covered, leaving no material gap for a single-parameter lookup.

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

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

Schema coverage is 100% and the sole parameter is documented, so the baseline is 3; the description adds genuine meaning by enumerating permalink as an accepted form and stressing exact case-insensitive name matching, which the schema's 'slug/name or record ID' phrasing does not make explicit.

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 (look up) and resource (glossary term), plus the accepted identifier forms and the return payload ('full definition and facets'). It also explicitly names the sibling tools it is not (search_esg, search_content, list_terms), so an agent can route 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 an explicit trigger ('what is <term>') and explicitly routes to alternatives for adjacent intents: search_esg/search_content for topical or cross-content lookup, list_terms for surveying the glossary. The when-not conditions are named alongside the tool that should be used instead.

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

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

Annotations only cover the safety profile (readOnlyHint/openWorldHint); the description adds ordering, page-by-page return behavior, the empty-result contract for no-match/over-run offsets, ~5-minute caching, per-IP rate limiting, and 5xx retry guidance. This is substantial behavioral context the annotations do not provide.

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

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

Dense but front-loaded: purpose and the sibling routing come first, then ordering/pagination, then constraints. Every sentence carries a distinct operational fact (values source, pagination mechanics, empty results, caching, retry) with no filler.

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

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

With an output schema present the description needn't explain return shape, yet it still clarifies how next_offset/has_more drive pagination. Combined with the filter sourcing rule and failure behavior, an agent has everything needed to call and loop this tool correctly.

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

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

Schema coverage is already 100%, but the description adds genuine semantics the schema lacks: `query` is an exact substring, not fuzzy; `section`/`pillar` values must be sourced from get_esg_metadata; `offset` is a raw row count advanced by `limit`. This meaningfully exceeds the schema's terse param descriptions.

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

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

States a specific verb+resource ('Enumerate ESG Hub articles') with explicit optional filters, and immediately names the sibling it is not ('to find articles by meaning use search_content'). An agent can distinguish it from search_content and search_esg 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 positive use case ('browse a whole section') and an explicit alternative with its selecting condition ('to find articles by meaning use search_content'). It also states prerequisites: section/pillar values must come from get_esg_metadata.

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 cover only read-only/open-world status; the description adds substantial behavior beyond them: title ordering, page mechanics (next_offset/limit/offset), empty-result semantics (empty list with has_more=false), ~5-minute caching, per-IP rate limiting, and 5xx retry guidance. This is well above the annotation baseline.

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

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

Purpose, routing, pagination, and operational caveats are front-loaded in one dense paragraph. Every sentence carries information, though the semicolon-chained operational notes (caching, rate limits, retry) make it slightly heavy to parse.

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

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

With an output schema present the description needn't detail return values, and it still clarifies the relevant fields (next_offset, has_more). Pagination, filtering constraints, empty-results, and failure/retry behavior are all covered, leaving nothing an agent needs to call it correctly.

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

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

Schema coverage is already 100%, so the baseline is 3. The description still adds value: 'query' is an exact substring (not fuzzy), 'domain' must be a host from get_esg_metadata's domain list, 'limit' caps at 100, and 'offset' should be advanced by 'limit' using the returned next_offset.

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 ('Enumerate curated external ESG resources') and enumerates the sub-categories (standards bodies, regulators, tools, databases). It explicitly distinguishes itself from the sibling 'list_esg_pages' for ESG Hub's own articles, so an agent can route without opening either schema.

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

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

Gives the use case ('assemble authoritative references'), names the alternative (list_esg_pages for internal articles), and points to get_esg_metadata as the source of valid domain values. Conditions for correct invocation are all present.

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 cover only readOnlyHint and openWorldHint, but the description adds substantial behavioral context: ~10-minute caching, per-IP rate limiting, retry-on-5xx guidance, and precise pagination semantics including the empty-items/has_more=false edge case. This is exactly the kind of operational detail annotations cannot express.

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

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

Purpose and field list come first, then sibling routing, then pagination and operational notes. Every clause carries information an agent needs; no filler or restatement of the title.

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

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

For a two-parameter list tool with an output schema, this is complete: it covers scope, routing, pagination mechanics, edge cases, caching, and rate limits. An agent has everything needed to call it correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real value beyond the schema: it explains that next_offset should be passed back as offset, that offset is a raw row count advanced by limit, and that an out-of-range offset yields an empty items list. It does not, however, clarify why a raw row count differs from page index, which is the one subtle risk.

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 (enumerate) and resource (ESG reporting frameworks/standards), lists the concrete items returned (abbreviation, description, website), and explicitly names the sibling it is not (list_esg_pages with section='standards'). An agent can distinguish it from list_esg_resources or list_esg_pages without opening a schema.

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

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

Explicitly says when to use this tool ('to discover coverage') and when to use an alternative ('for the ESG Hub articles that explain a standard use list_esg_pages with section=standards'), even supplying the exact parameter value. Nothing is left to inference.

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

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

Annotations already cover readOnly/idempotent/openWorld=false, but the description adds substantial context beyond them: no pagination, complete single-response return, taxonomy is seeded/stable reference data, ~10-minute cache, per-IP rate limiting, and 5xx retry guidance.

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

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

Front-loaded with what the tool returns, then use cases, then routing alternative, then operational traits. Every sentence carries a distinct fact with no filler.

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

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

Output schema exists so return values need not be re-explained, yet the description still summarizes the fields an agent needs for planning. Combined with the operational notes (cache, rate limit, retry), nothing required 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?

The tool takes zero parameters, so the baseline is 4. The description correctly states it takes no parameters, and there are no parameter semantics to add.

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

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

States a specific verb+resource and details the exact content returned: the ESG Hub industry taxonomy with industry_id, English/Chinese names, and sector_id. It also distinguishes itself from siblings by noting get_esg_metadata is the tool for article sections and source domains.

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

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

Gives explicit use cases (obtain valid industry values for tag_content, group coverage by sector) and names the alternative tool for the adjacent need (get_esg_metadata). An agent can route correctly without inference.

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

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

Annotations only cover readOnlyHint/openWorldHint; the description goes well beyond by disclosing result ordering by name, paging mechanics, empty-result behavior for no matches or over-range offsets, a ~10-minute cache, per-IP rate limiting, and retry-on-5xx guidance. This is unusually rich operational 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?

Front-loaded with the core action and filter, then routing guidance, then pagination rules, then operational caveats. Every sentence carries distinct information; no filler.

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

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

Given low-complexity read semantics, annotations, full schema coverage, and an output schema (so return values needn't be re-explained), the description covers routing, pagination, filter behavior, and failure/retry modes. Nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is already 100%, but the description adds semantics the schema lacks: query is an exact case-insensitive (not fuzzy) name substring, offset is a raw row count advanced by limit, and how next_offset should be passed back. It also confirms defaults/caps rather than merely restating them.

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 (enumerate) and resource (glossary terms) with scope (optional exact-substring name filter). It names the siblings it is not — get_term for a single definition, search_esg/search_content for full-content search — so an agent can route without opening other schemas.

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

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

Explicitly states when to use it (survey the glossary, page through terminology) and names the alternatives for adjacent tasks (get_term for one definition, search_esg/search_content for cross-content search). No exclusions are left to inference.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=false, so the mutation/safety profile is covered. The description adds substantially more: nothing publishes immediately, a pending proposal is created, a proposal_id is returned, a reviewer gates publication, a write token in ESG_HUB_WRITE_TOKEN is required and a missing/invalid token yields 401, and calls are rate-limited.

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

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

Front-loaded with the essential outcome (pending proposal, no immediate publish) and then routing, params, and auth. Dense but every clause carries information; slightly long with several semicolon-joined clauses, though nothing 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?

For a mutation tool with an output schema, the description covers outcome semantics (pending vs. live), the returned proposal_id, auth requirements, and rate limits. An agent has everything needed to call it correctly and to explain the result to a user.

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, but the description adds meaning beyond the schema: it clarifies that name is the display name, that definition must be at least 10 characters, and that facets values should be drawn from the get_esg_metadata / list_industries vocabularies. That vocabulary-source guidance is genuinely new information not present in the schema.

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

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

States a specific verb (submit for review) and resource (glossary term), and explicitly distinguishes itself from the read path by noting that only approved terms later appear in get_term. An agent can separate this from list_terms/get_term 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 an explicit when-to-use condition ('only when the user explicitly wants to contribute a term') and names the alternative ('to look one up use get_term'). The when-not is stated, not 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 only provide readOnly/openWorld hints; the description adds substantial extra context: no pagination, ranked single page with fused scores, empty-list-on-zero-matches, ~2-minute caching, per-IP rate limiting, and 5xx retry guidance. That is rich operational disclosure beyond the structured fields.

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

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

Dense but front-loaded and well ordered: purpose, routing, then constraints and operational notes. A couple of facts (limit default 10, cap 50) duplicate the schema, minor redundancy for an otherwise efficient passage.

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?

An output schema exists so return-value detail is optional, yet the description still explains the ranked page, score semantics and empty-list behavior. Combined with caching/rate-limit notes and the search_esg contrast, nothing an agent needs to call this correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3; however, the description adds genuine meaning not in the schema — that `query` is embedded (so NL phrases beat single tokens) and that `limit` is capped at 50 with no pagination to widen results. It slightly repeats the schema's default/cap, keeping it from a 5.

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

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

States a specific verb+resource (hybrid search over ESG Hub articles and external resources) and details the fusion mechanism (384-dim semantic + BM25 + ESG re-ranking). It is immediately distinguishable from the sibling search_esg, which it names explicitly.

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

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

Gives explicit when-to-use ('conceptual or paraphrased questions', natural-language phrases) and when-not ('exact identifier or phrase prefer the cheaper search_esg'), with the reason (query is embedded). This is textbook 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?

Goes well beyond the readOnlyHint/openWorldHint annotations by disclosing matching semantics (terms matched individually, not as a phrase), the absence of pagination and how to widen results, empty-result behavior (empty list, not an error), ~2 minute read caching, per-IP rate limiting, and 5xx-means-redeploy retry guidance. This is exactly the operational context annotations cannot carry.

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

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

Front-loaded with purpose and the sibling contrast before operational details, and nearly every clause carries distinct information. It is dense and slightly long as a single block, but there is little true filler.

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

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

With an output schema present, return shape need not be described, and the description still covers matching semantics, result volume/pagination, empty results, caching, rate limits, and failure modes. Nothing an agent needs to invoke and interpret this tool correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real semantics the schema lacks: what 'pages' vs 'external' actually mean for `source`, and that `limit` caps at 50 with no pagination (raise limit to widen). The query-matching behavior is also clarified. It stops short of full per-parameter treatment, so not a 5.

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

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

States a specific verb and mechanism (exact keyword/BM25 search) over a named resource (ESG Hub articles and curated external resources), and explicitly contrasts itself with the sibling search_content. An agent can distinguish it from search_content without opening either schema.

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

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

Gives an explicit when-to-use trigger (user supplies a specific term, identifier, or phrase, with examples 'GRI 305', 'Scope 3') and an explicit when-not with the named alternative (paraphrased/conceptual questions → search_content, which adds semantic similarity). Nothing is left to inference.

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

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

Goes well beyond the annotations: the replace-not-merge semantics ('any facet key you omit is cleared'), the guarantee that body/title are untouched, the echoed return fields, 400-on-invalid-value behavior, required ESG_HUB_WRITE_TOKEN, and rate limiting. This is exactly the mutation-behavior context annotations cannot carry.

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

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

Front-loaded with the replace action and clearing semantics, and every sentence carries information. It is dense and slightly run-on, but nothing is filler.

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

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

An output schema exists, yet the description still frames the response briefly; combined with write-token, rate-limit, validation, and clearing behavior, an agent has everything needed to call it correctly.

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

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

Schema coverage is 100%, so types are already documented, but the description adds real semantics: which facets are multi-value arrays vs the single-string content_type, that values are validated against the get_esg_metadata/list_industries vocabulary, and that page_id accepts permalink/slug/record ID with server-side resolution.

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

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

Opens with a specific verb+resource+scope ('Replace the facet tags on one existing ESG Hub page') and enumerates the exact facet keys affected. An agent can immediately distinguish this from get_esg_page and flag_content.

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 routing: 'Use it to curate tags; to read a page use get_esg_page, and to queue a removal use flag_content.' It names both the read and removal alternatives and the condition selecting each.

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