ESG Hub MCP Server

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

The annotations already declare readOnlyHint=true, idempotentHint=true, and openWorldHint=false, and the description largely restates those ('Read-only and idempotent') rather than adding new behavioral context. It does confirm this is a discovery/aggregation call, but contributes little 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?

Two sentences, front-loaded with the core purpose and followed by the usage directive. Every clause earns its place 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?

An output schema exists, so return-value documentation is not required, and the description still sketches the shape of the response (sections, pillars, domains with counts). Combined with the sibling routing guidance, 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?

The tool takes zero parameters, so there is no parameter semantics to convey and the baseline of 4 applies. The description correctly implies a no-argument, whole-corpus query.

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

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

States a specific verb and resource ('Get ESG Hub knowledge-base statistics') and enumerates the returned collections (sections, pillars, source domains with counts). This clearly separates it from sibling list tools like list_esg_pages and list_esg_resources.

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 to call it before filtering with list_esg_pages or list_esg_resources to discover valid filter values, which is strong when-to-use guidance naming alternatives. It stops short of stating exclusions or failure conditions, so it is not a full 5.

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

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

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint=false, and the description largely restates that with 'Read-only and idempotent,' adding little beyond structured data. It does mention the returned fields, but an output schema exists so that is redundant. No permission, rate-limit, or error-handling context is added.

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: purpose first, then usage routing, then return/safety notes. Every sentence carries information and nothing is padded.

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

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

For a single-parameter read tool with full schema coverage, complete annotations, and an existing output schema, the description covers purpose, routing, and identity of the resource. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 100% and the single page_id parameter is already documented with its permalink/slug/record-ID forms and an example. The description's 'by permalink, slug, or record ID' repeats the schema rather than adding new meaning, so the baseline 3 applies.

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

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

States a specific verb (Retrieve) and resource (full content of one ESG Hub article) with the accepted identifier forms. It also names the sibling tools it complements (search_esg, search_content, list_esg_pages), so an agent can distinguish it from the list/search tools 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 says when to use it: 'after search_esg, search_content, or list_esg_pages to read a specific article.' This names three alternative tools and the sequencing condition that selects this one over them.

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=false, so 'Read-only' is redundant with structured data. The description does add genuinely non-annotation context: traversal semantics and the grouping of results by edge type. It omits depth limits, pagination, or behavior when no edges exist.

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 compact sentences, front-loaded with the action and return shape, followed by routing guidance. No filler, though 'Read-only' duplicates the annotation and consumes a clause.

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-value detail is unnecessary, and the description covers purpose, return grouping, and the key alternative. It is sufficient for an agent to select and call the tool correctly; only traversal-depth/pagination nuances are absent.

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

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

Schema description coverage is 100%, so both parameters are already documented in the schema. The phrase 'grouped by edge type' loosely reinforces the edge_type filter, but no format or syntax detail is added beyond what the schema provides.

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

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

The description names a specific verb and resource ('Traverse the ESG Hub knowledge graph from a page') and states what it returns ('connected records grouped by edge type'). It also distinguishes itself from the sibling get_esg_page, so an agent can tell the two apart 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?

It gives clear context ('Use to explore how concepts interconnect') and routes content-reading to the alternative, get_esg_page. There is no explicit statement of when not to use it, but the routing guidance is strong.

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. The description adds meaningful context beyond them: 'it reads no content', which distinguishes this metadata probe from the content-fetching siblings, and it enumerates the returned stat categories. It adds no notes on failure modes or cost, so not 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?

Two sentences, zero waste, and the actionable instruction ('use this first') is front-loaded before the return-value enumeration. 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?

For a parameterless, read-only orientation tool with annotations covering the safety profile and an output schema covering the return shape, the description supplies everything an agent needs: when to call it, what it yields, and that it touches no content.

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 per the rubric the baseline is 4. Nothing about argument semantics needs explaining, and the description correctly focuses on behavior and return shape instead.

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 (get server info) and enumerates exactly what it returns: server name, version, API base, and aggregate stats. It also positions itself relative to siblings as the orientation step taken 'before choosing other tools', so an agent can distinguish it from the content/search tools without opening a schema.

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

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

Explicitly says 'Use this first ... before choosing other tools', which is a clear routing rule for when to invoke it. It stops short of naming a when-not condition or a specific alternative sibling, which keeps it from a 5.

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

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

Annotations already declare readOnlyHint, idempotentHint and openWorldHint=false, so 'Read-only and idempotent' largely repeats structured data. The description does clarify the lookup-by-identifier behavior and that the full definition is returned, which is modest added context but not rich behavioral disclosure.

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 purpose, then usage routing, then a return/safety note. Efficient, with only the redundant read-only/idempotent claim not earning much place against the annotations.

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

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

A single-parameter, read-only lookup with an output schema, so return-format detail is not required. Purpose, routing and accepted identifiers are all covered; 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 100% and the single term_id parameter is well documented in-schema. The description adds one genuinely new fact — that a permalink is also accepted, alongside schema's slug/name and record ID — but otherwise does not extend parameter meaning.

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 ('Fetch a glossary term') and immediately names the accepted lookup keys. It also distinguishes itself from search_esg and search_content, so an agent can route correctly without opening the schema.

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

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

Explicitly gives the when ('user asks about specific ESG terminology') and the alternative for a different intent ('to search for terms by topic use search_esg or search_content'). The selection condition is unambiguous.

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

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

With readOnlyHint=true and openWorldHint=false already declared, the safety profile is covered, and the description adds real behavioral context: results are paginated and next_offset must be passed back as offset. The dependency on get_esg_metadata for valid enum-like values is also disclosed, though error/empty-result behavior is not.

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 purpose, then usage, then the pagination mechanic and prerequisite. Every sentence carries distinct information with no repetition of the 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?

For a read-only, zero-required-parameter listing tool with a full schema and an output schema, the description covers purpose, usage, pagination, and the prerequisite lookup. Return-value shape is delegated appropriately to the output schema, leaving little 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 every parameter (limit, query, offset, pillar, section) is already documented in the schema, including the next_offset convention for offset. The description restates the filter dimensions in prose without adding syntax or format detail, so the baseline of 3 applies.

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

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

States a specific verb and resource ('List and filter ESG Hub articles') plus the three filter axes (section, pillar, title substring), so the agent knows exactly what the tool returns. It does not differentiate itself from the similar-sounding siblings search_esg or list_esg_resources, which is why 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?

Gives clear positive usage ('browse the knowledge base or enumerate a domain') and an explicit prerequisite ('Call get_esg_metadata first to discover valid section/pillar values'), which is genuinely actionable guidance. It stops short of naming when to prefer search_esg over this listing tool, so no explicit exclusion is 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 establish readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds non-obvious behavior beyond that: results are paginated and next_offset should be passed back as offset, plus the dependency on get_esg_metadata for valid domain values.

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

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

Three compact sentences, each earning its place: scope, usage, pagination mechanics, and prerequisite. Front-loaded with the resource definition and no filler.

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

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

For a filtered, paginated list tool with an output schema (so return values need no prose) and annotations covering the safety profile, the description covers everything an agent needs: what it returns, how to page, and where to get valid domain inputs.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds real value by explaining the pagination contract (next_offset -> offset) and by directing the agent to get_esg_metadata to obtain legal domain values, which the schema's example does not supply.

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

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

States a specific verb and resource ('List curated external ESG resources') and enumerates what the collection contains (standards bodies, regulations, tools, databases) plus the payload (source URLs). This is clearly distinct from get_* siblings, though it never names an alternative like search_esg, so it stops short of full sibling differentiation.

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 usage context ('find authoritative references by domain or title') and a hard prerequisite ('Call get_esg_metadata first for valid domain values'). It does not state when NOT to use it or contrast it against search_esg, so it lacks the exclusions that would push it to a 5.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds a pagination behavior note beyond what annotations convey, though it does not describe return shape (an output schema exists, so that is acceptable).

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, front-loaded sentences with zero filler: purpose and examples first, then routing guidance, then a pagination flag. Every sentence 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?

For a simple two-parameter, read-only list tool with full schema coverage and a dedicated output schema, the description supplies everything an agent needs: scope, examples, routing alternative, and pagination awareness.

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

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

Schema description coverage is 100% and both pagination parameters are self-documented, so the schema carries the parameter burden. The description adds only the general 'Paginated' note and no syntax or default semantics beyond the schema.

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

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

States a specific verb and resource ('List ESG reporting frameworks and standards') and enumerates concrete examples (GRI, SASB, TCFD, ESRS, CDP), making it immediately distinguishable from siblings like list_esg_pages or list_industries.

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

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

Explicitly gives the use case ('discover which frameworks the knowledge base covers') and names an alternative with its exact selecting argument ('for related article content use list_esg_pages with section='standards''), so routing is unambiguous.

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

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

The annotations already declare readOnlyHint=true and idempotentHint=true, and the closing sentence merely restates those facts, earning no extra credit. The description does add behavioral value by disclosing the taxonomy's style (IFRS/SASB) and that results are grouped by sector, which helps the agent anticipate the shape of the output. It stops short of richer context such as whether the list is complete or filtered.

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 front-loaded with the key fact: what it lists, when to use it, and its safety profile. No filler or redundancy.

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

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

For a zero-parameter, read-only listing tool with an output schema in place, the description covers everything an agent needs: identity of the taxonomy, intended use for discovery and tagging, and grouping structure. No return-value explanation is required since the output schema handles that.

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. There is no parameter syntax or format to document, and the description correctly adds nothing spurious on this front.

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

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

States a specific verb and resource ('List the ESG Hub industry taxonomy') and adds scope detail (IFRS/SASB-style, grouped by sector). This is clearly distinguishable from siblings like list_frameworks or list_esg_resources, which handle different taxonomies entirely.

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 use case: 'Use to discover valid industry values for tagging and filtering.' That gives the agent a clear trigger, but it names no alternatives or when-not-to-use conditions (e.g., when to use it vs. 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 only declare readOnlyHint=false and destructiveHint=false, so the write nature is already implied. The description adds real context beyond that: an auth requirement (valid token in ESG_HUB_WRITE_TOKEN), the human-review gate, and the returned proposal ID/status.

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

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

Three compact sentences, front-loaded with the action and scope, then the usage condition, then the auth/return facts. Every sentence 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?

Covers the workflow (proposal for human review), the gating prerequisite (write token), and even the return values despite an output schema existing. Nothing critical for correct invocation is missing, though a note on whether the proposal can be amended later would be a bonus.

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%, including the nested facets object, so the schema already documents all three parameters. The description adds no syntax or format detail for name/definition/facets, making the baseline 3 correct.

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 ('Submit a new glossary term proposal') and adds the crucial scope detail that it goes to human review before publication, which distinguishes it from the read-oriented siblings like get_term and search_esg.

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

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

Explicitly scopes usage with 'Use only when the user wants to contribute a term', which sets a clear condition. It does not name a sibling alternative or state exclusions (e.g., editing an existing term), so it falls short of a full when/when-not/alternatives treatment.

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 the safety profile (readOnlyHint=true, openWorldHint=false), and the description adds genuine value beyond them by disclosing the retrieval architecture and that results are ranked by a fused relevance score. It stops short of discussing pagination or result-shape behavior, so not 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 capability, then usage guidance, then ranking note. Every sentence carries information and nothing is padded.

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

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

An output schema exists, so return value structure needn't be repeated. For a low-complexity, two-parameter read-only search, the description plus annotations plus schema cover everything an agent needs to select and 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% for both parameters, so the schema already documents query format and limit bounds. The description adds no parameter-level detail beyond what the schema provides, making baseline 3 appropriate.

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

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

States a specific verb+resource ('hybrid semantic + keyword search across all ESG Hub content') and immediately distinguishes itself from the sibling search_esg. The mechanism (vector + BM25 + re-ranking) makes the tool's identity unambiguous.

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

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

Explicitly says when to use this tool ('nuanced or conceptual queries') and names the alternative with its own condition ('for exact keyword/phrase lookups use search_esg'). This is textbook routing guidance.

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

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

Annotations already cover the safety profile (readOnlyHint=true, openWorldHint=false), so the bar is lower. The description adds useful retrieval semantics — that it is BM25-ranked rather than semantic — which affects how results should be interpreted, but says nothing about pagination or result-count 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 waste: purpose first, then routing guidance, then return shape. The most decision-relevant content (what it searches, when to choose it) is front-loaded.

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 spelled out, annotations carry the safety profile, and the description covers purpose, routing, and ranking model. An agent has everything needed to select and call 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 description coverage is 100%, so query, limit, and source are all documented in the schema itself. The description's mention of source type in the return shape hints at filtering but adds no syntax or semantics beyond what the schema already provides; 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 ('Full-text keyword (BM25) search across all ESG Hub articles and external resources') and explicitly names the sibling it is not — search_content — so an agent can distinguish the two 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 ('exact term or keyword lookups') and an explicit when-to-use-the-alternative ('nuanced/conceptual queries that benefit from semantic similarity, use search_content'). 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 beyond the annotations by flagging this as a write operation requiring ESG_HUB_WRITE_TOKEN, which the annotations alone would not convey. It still leaves a meaningful behavioral gap: whether the supplied facets replace all existing tags or merge with them is not stated, which matters for a tagging mutation.

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

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

Three tight sentences, front-loaded with the action, then the rationale, then the restriction and alternative. 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?

An output schema exists, so return values need not be explained, and the auth requirement is stated. The one missing piece is merge-vs-replace semantics for the facets payload, which an agent would need to call this mutation safely.

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 nested facet object is documented per-property in the schema, so the schema does the heavy lifting. The description adds the purpose of facets (filtering, discoverability, graph navigation) but no additional parameter syntax or format guidance.

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

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

Names a specific verb (update) and resource (facet tags on an ESG Hub page), and states the accepted identifier forms. It also explicitly distinguishes itself from the sibling get_esg_page, which reads the same resource.

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

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

Provides an explicit when-not ('Use only to change tags') and names the alternative operation for reading ('to read a page use get_esg_page'). Routing is unambiguous.

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