dVeracity Semantic API

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and openWorldHint=false, so safety and determinism are covered. The description adds that the output covers per-plan inclusions and the free-tier allowance, but says nothing about whether it is a static catalog versus live data, or anything about shape or freshness.

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

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

It is short and front-loads the use case, but the second sentence largely restates the first ("what each plan includes" appears twice), so one of the two sentences does not fully earn its place. Trimming to a single sentence with a scope note would be tighter.

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 reference tool with no output schema, the description tells the agent what content to expect (plan list, plan inclusions, free-tier allowance). Little else is needed to invoke it correctly, though a note that it is static plan reference rather than account state would fully close the gap.

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

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

The tool takes zero parameters, so there is no parameter semantics to explain and the baseline of 4 applies. The description correctly avoids inventing any filtering or argument behavior.

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 uses a specific verb ("Show") and a specific resource (dVeracity plans, plan contents, free-tier allowance), so an agent can tell it returns a static catalog of plan information. It does not explicitly differentiate itself from siblings like billing_status or credits_balance, which cover account-specific status and balances, 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?

"Use this when you need to know what each dVeracity plan includes or what the free allowance covers" gives a real when-to-use condition. However, it offers no exclusions or routing guidance against the similar-sounding billing_status and credits_balance siblings, leaving the agent to infer that this is reference data rather than account state.

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 destructiveHint=false, so the agent knows this is a safe, repeatable read. The description adds the useful behavioral detail that the tool exists to explain a prior 402 failure to the human. It does not disclose what data comes back, whether calling it has any cost, or what happens outside a 402 context.

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

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

Two sentences say essentially the same thing: 'tell the user exactly what is missing' appears verbatim in both. The trigger is front-loaded, which is good, but the second sentence is pure redundancy and displaces content that would actually be useful, such as what fields are returned.

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 parameters and no output schema, the description is the only source of information about the return payload, and it never states that the tool surfaces balance, plan tier, or remaining credits. For a diagnostic tool invoked under a 402, the agent needs to know what it will learn. The trigger guidance is complete; the result expectations are not.

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 nothing for the description to disambiguate. The baseline of 4 applies; the description correctly implies the tool is parameterless because it is scoped entirely by the caller's account context.

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 frames the tool around its trigger condition ('when a call was refused for credits or plan') rather than stating plainly what it returns. The title 'Account balance and plan' carries most of the resource identification, while the body only says it will 'tell the user exactly what is missing'. An agent can infer it is a billing diagnostic read, but the purpose is described indirectly.

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 an explicit, concrete trigger: after a 402 refusal due to credits or plan. That is stronger than most definitions and tells the agent precisely when to reach for this tool. It stops short of naming alternatives (credits_balance, billing_plans) or stating when not to use it, so it is clear context without exclusions.

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?

Well beyond the annotations (which only mark it non-read-only, non-idempotent, non-destructive): the description discloses the five decision outcomes, that an error is a refusal and never compliance, the specific error.code values, the scope requirement (compliance:evaluate), and that every call counts against the plan limit. The remaining gap is that the response payload shape and the meaning of coverage.note are only alluded to, and nothing explains the cost or side effect implied by readOnlyHint=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?

Front-loaded with the use case and exclusions, then behavior, then parameter guidance; every sentence carries information. It is dense, and the parenthetical error-code list is a long enumeration, but it is genuinely needed to interpret refusals rather than 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 seven-parameter, nested-object tool with no output schema, the definition covers the decision semantics, refusal semantics, scope, and billing impact, which are the highest-risk unknowns. It stops short of describing the evaluation result contents or what entity/context/evidence should contain, which is the main remaining hole.

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 low (29%), so the description must carry weight; it adds real meaning for entity_type (cbam_declaration vs. the carbon_measure default) and for the declaration/lines pairing, plus the acceptance criterion on evidence. But entity, context, and policy_id receive no semantic explanation at all, leaving several nested-object parameters undocumented in both places.

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 precise verb and scope: checking an import record or an annual EU CBAM declaration against an approved policy before filing. It explicitly separates this from the generic OFP validator and from carbon-footprint calculations, so an agent can distinguish it from ofp_validate and the compliance_policies family 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 an explicit when-to-use condition ('before filing'), two when-not-to conditions (carbon-footprint calculations, regulations not listed by compliance_policies), and names an alternative (the generic OFP validator, via ofp_validate). It also supplies the concrete invocation pattern for the CBAM case: set entity_type to cbam_declaration and send declaration + lines.

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 readOnly, idempotent, non-destructive behavior, and the description goes well beyond that: it discloses ownership scoping (only the caller who ran it can read it), the not-found response for another account's id, and the required compliance:read scope. These are exactly the auth and error semantics an agent needs and cannot get from 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, use-case first, then access and error constraints. No redundant restatement of the title or annotations, and every clause adds information.

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

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

For a one-parameter read tool with full annotations, the description covers when to call, permission requirements, and error behavior. The one gap is the return shape, which is undocumented since no output schema exists, so an agent cannot anticipate the evaluation fields returned.

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 0% and the single parameter has no description, so the description carries the burden; it explains that the id identifies a previously run evaluation rather than an arbitrary record. It does not state the UUID format, but that is visible in the schema itself.

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 pair (retrieve or audit) and a specific resource (a previous regulatory evaluation) keyed by id. The word 'previous' implicitly separates it from compliance_evaluate, which produces a new result, though that sibling is never named outright.

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 a clear triggering condition ('when a user wants to retrieve or audit a previous regulatory evaluation') and states the access prerequisite (compliance:read). What is missing is an explicit pointer to compliance_evaluate for running a fresh evaluation, so the when-not side 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 readOnly, idempotent, non-destructive, but the description adds the behavior that actually matters: only APPROVED policies are returned, drafts and rejected are excluded, an empty list means nothing published rather than no obligations, and it warns against inventing rules. That is genuine disclosure beyond the hint set.

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 routing condition and followed by output semantics and the permission requirement. Slightly dense but no sentence is filler; the only lost point is that parameter guidance is absent rather than over-explained.

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 does explain the shape of the result (approved-only list, empty-list meaning) and the auth requirement, which is the important part. However, for a 3-parameter filter tool with zero schema documentation, the caller still cannot know what to put in domain or framework, leaving a real 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?

All three parameters (domain, framework, include_retired) have 0% schema description coverage and the description says nothing about them — no expected values, no format for domain/framework, no clarification of what include_retired actually toggles. The only related statement, "returns only APPROVED policies; drafts and rejected never appear", arguably leaves an agent unsure how retired policies interact with that filter.

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 (find/list the approved policy to run a regulatory check) and grounds it with a concrete example (EU CBAM). It explicitly names the sibling it is not (ofp_policies for Open Footprint sector rules), 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 a positive trigger (user needs data checked against a regulation), an explicit exclusion with the alternative named ("Do not use for Open Footprint sector rules; use ofp_policies"), and the prerequisite scope (compliance:read). Nothing about when-to-use 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 (which only declare read-only/idempotent/closed-world) by disclosing the rego_unavailable: source_not_retained fallback, the fact that a policy without Rego is not loaded into the engine, the meaning of the enforcement field, and the required compliance:read scope. These are exactly the behavioral details an agent cannot infer from 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?

Four tight sentences, each adding distinct value: use condition, return semantics, fallback behavior, and authorization requirement. The use condition and the key caveat are front-loaded and nothing is repeated 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?

With no output schema and no annotation detail, the description supplies the return payload (rules, provenance, coverage, Rego, enforcement) and the degraded-path marker, which is substantial. It leaves the exact response shape and the source of the id unclear, but an agent has enough 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?

Only one parameter (id, uuid) with 0% schema description coverage, so the description must carry meaning. It establishes the parameter selects exactly one approved policy, but never says the id is the policy identifier or where it comes from. Partial compensation, not full.

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: retrieve the full rules, provenance and coverage of one approved regulatory policy. That distinguishes it from the plural listing sibling compliance_policies and from compliance_evaluate, though neither sibling is named explicitly. An agent can tell this is a single-policy detail fetch, not an evaluation or a list.

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

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

Opens with an explicit selection condition ('Use this when you need the full rules, provenance and coverage of one approved regulatory policy') and adds a behavioral guardrail ('Do not reconstruct the Rego'). It does not name alternatives or state when NOT to use it (e.g., use compliance_policies to browse, compliance_evaluate to run), so it stops short of 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 read-only, idempotent, non-destructive behavior, but the description adds useful context beyond them: it requires the compliance:read scope and warns that a pass on encoded checks is not compliance with excluded provisions. It does not describe response shape or pagination, but those are less critical given 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?

The description is two short paragraphs: the usage condition is front-loaded, followed by the key caveat and auth scope. There is no filler or repetition.

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 read-only lookup, the description covers purpose, an important limitation, and authorization scope. However, it leaves the only identifier undefined and does not say what the returned register contains beyond the general statement about encoded versus excluded provisions.

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 0%, and the sole required uuid parameter 'id' is never explained in the description. An agent cannot tell from the definition whether this id identifies a policy, a regulation, or an evaluation, so the description adds essentially no parameter meaning beyond the schema.

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

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

The description states a specific informational purpose: showing which regulation provisions an evaluation actually encodes and which it excludes, framed around a user question. It is distinguishable from evaluation siblings, though it never explicitly names the policy/register resource or what the lookup id represents.

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 an explicit when-to-use condition: when a user asks which provisions of a regulation an evaluation checks and which it does not. It does not name when to use a sibling such as compliance_evaluate or compliance_policy instead, nor does it state exclusions.

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 destructiveHint=false, so the safety profile is covered. The description adds genuinely new behavioral context the annotations cannot express: the tool is deprecated and scheduled for removal in 0.9, which should influence an agent's choice. It still says nothing about the returned data shape or whether the value is stale/live.

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 short sentence, front-loaded with 'Deprecated' so the most decision-relevant fact lands first. Every clause (replacement name, its advantage, removal version) carries information; 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?

For a simple no-parameter read tool with full annotation coverage, the deprecation and migration guidance covers the main decision. However, there is no output schema and the description never says what the balance response contains, so an agent cannot judge whether the replacement returns comparable data.

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 takes zero parameters, so there is nothing for the description to disambiguate; the baseline for a parameterless tool applies. No parameter claims are made or contradicted.

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 never states what the tool actually returns; the only clue is the name and title ('Credit balance'). It devotes its whole text to deprecation status and a migration path, so an agent must infer the function from the identifier rather than from a stated verb+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?

It explicitly names the replacement (billing_status) and adds why ('which also shows plan and free allowance'), plus a lifecycle horizon ('Removal planned for 0.9'). What's missing is an explicit statement of whether the tool still works today or should be avoided entirely, though the removal timeline implies it is still callable.

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, non-destructive, closed-world, so the safety profile is covered. The description adds the useful gate that it is only meaningful when vLEI is configured, but says nothing about what the response contains or how a missing/unconfigured identity is signalled.

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

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

Two short sentences with no filler, and the use condition is front-loaded. Minor awkwardness in the 'attributing calls to' phrasing keeps it from a 5.

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

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

For a zero-param read tool with no output schema, an agent still does not know what fields come back (entity name, LEI, KERI AID, attribution scope) or how to interpret the tool when vLEI is not configured. The description covers when to call it but not what to expect from 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?

Zero parameters, so the baseline is 4. The description correctly implies no input is needed beyond ambient configuration, which matches the empty schema.

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

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

The description names a specific resource: the verified legal entity and agent identity that dVeracity attributes calls to. It is clear about what is retrieved, though the phrasing 'keri' vs 'vLEI' vs 'agent identity' leaves a little ambiguity about exactly which identifier is returned.

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 states an explicit triggering condition ('when an organisation needs to confirm which verified legal entity and agent identity...') and a precondition ('Only relevant when vLEI identity is configured'). No sibling alternative is named, but none of the listed siblings overlaps closely enough for that to matter much.

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, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered by structured data. The description's only added behavioral value is the dependency relationship with validate_data; it says nothing about the shape of the returned list, ordering, or whether versions are grouped per standard. With annotations carrying the burden, a 3 is appropriate.

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 sentence with the usage trigger front-loaded and no filler. Every clause contributes either the trigger or the dependency on validate_data.

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 discovery tool whose annotations already state the safety and idempotency profile, this is sufficient: the agent knows what it returns conceptually (standards plus versions), why to call it, and in what order relative to validate_data. No output schema exists, but the description conveys the content of the result well enough to act on.

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 leaves nothing to interpret and the baseline of 4 applies. The description correctly implies the call is unfiltered and complete rather than scoped by any argument.

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 the concrete resource: sustainability data standards and their versions that validate_data can check. It also distinguishes the tool from the large sibling set by tying it explicitly to validate_data, so an agent can tell it apart from validation or semantics tools. The verb is slightly implicit ("see which ...") rather than a direct "list," which keeps it just below 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 gives an explicit trigger condition ("Use this when you need to see which standards ... can check") and a sequencing rule ("before calling it" referring to validate_data), which is the key routing decision an agent faces. It stops short of stating when not to use it or what to do if the standard is already known.

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 the safe-read profile (readOnly, idempotent, non-destructive, closed-world), so the description's job is to add operational detail — which it does by disclosing that ambiguous names fail rather than guessing and by pointing to ofp_models for ambiguousNameCount. That is genuine failure-mode disclosure well beyond the annotations, though it says nothing about response shape or lookup cost.

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

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

Two short sentences, front-loaded with the trigger condition, and every clause carries information the agent cannot get from the schema or annotations. 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 no output schema, the description correctly previews the return contents (fields, types, keys, relationships) and covers the main failure mode. It falls short of complete because the required name parameter's semantics and the relationship to sibling lookups (search, semantic code) are left unstated for a tool in a crowded namespace.

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 0%, so the description carries the full burden for two parameters. It explains why domain matters (disambiguation) but says nothing about its expected form or scope (domain id vs. name), and leaves the required name parameter entirely implicit.

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 resource and payload: one entity's fields, types, keys and relationships, plus a concrete use case (designing a table or API payload). It implicitly contrasts with broader lookups by emphasizing 'one entity', but never names a sibling such as ofp_search_entities or ofp_semantic_code, so the differentiation is inferential rather than explicit.

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 a clear trigger condition ('when you need one entity's fields...') and a conditional rule for the optional domain parameter ('Pass domain when known'). What is missing is an explicit statement of when NOT to use it or which sibling to reach for instead when the entity name is unknown.

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, destructiveHint=false, and openWorldHint=false, so safety and side-effect expectations are covered. The description adds the informational scenario but says nothing about the return value, source of the version, or whether it reflects a pinned or latest standard.

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 sentence with no waste, front-loaded with the usage condition. Nothing is repeated or 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 zero-parameter informational tool with no output schema, the description should ideally state what is returned, such as the version string or provenance details. It clearly sets the user question but leaves the return shape implicit.

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 has zero parameters, so the baseline score is 4. There is no parameter behavior to clarify and the schema requires nothing further.

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 frames the tool around answering which version of the Open Footprint standard is in use, which is a clear informational purpose. It does not explicitly say it returns a version identifier, but the title and wording make the resource and intent distinguishable from siblings like ofp_models or list_standards.

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 an explicit trigger: use when a user asks which version of the Open Footprint standard they are designing against. It does not mention exclusions or name alternative tools, but the usage context is clear and specific.

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 readOnly, idempotent, non-destructive and closed-world, so the safety profile is fully covered without the description. The only added behavior is that 'the response summary carries the served counts', which tells the agent something about the response envelope but is vague about what 'served counts' means. Nothing is said about caching, rate limits, or what the payload otherwise 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 short sentences plus one line, front-loaded with the trigger condition and the ordering rule. The trailing sentence about 'served counts' is cryptically worded jargon that does less work than its length suggests, but overall there is 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 zero-parameter read tool with no output schema, the description should say what the caller actually gets back — a list of model domains/sectors and their identifiers. Instead it only mentions 'served counts' in the response summary, leaving the return shape underspecified. The entry-point guidance is complete, but the informational content is not.

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 — baseline 4 applies. The description correctly avoids inventing arguments and instead focuses on when to call it.

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 never states the operation outright — there is no verb such as 'list' or 'returns the model domains'; it only says the user 'needs to know what the model covers'. The title carries the real meaning ('list model domains'), and the description gestures at it indirectly. It does separate itself from siblings via the 'start here before any other ofp_ tool' framing, which helps routing.

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 trigger scenario (building a database, application or integration on the Open Standard) and an explicit ordering rule relative to every sibling ('start before any other ofp_ tool'). No when-not-to-use case or named alternative is given, but for an entry-point tool the positive 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 this read-only, idempotent and closed-world, so the description is not burdened with safety disclosure. It adds genuinely non-obvious behavioral context: that 'inputs' reports raw e-ledger field names rather than canonical Open Footprint names, and that published:false means no rules exist and the agent must not fabricate guardrails. It does not sketch the overall response shape, but the anti-hallucination guidance is the highest-value thing it could say.

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: the trigger and exclusion come first, then the two caveats about response content. No restatement of the tool name or title, 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 a single parameter, no output schema, and annotations covering safety, the description covers most of what is needed, including a key anti-fabrication rule. The gap is the undefined 'id' parameter, which leaves ambiguity about whether the lookup is sector-scoped or policy-scoped. Complete on behavior, incomplete on input contract.

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 0% for the single required parameter 'id', so the description must explain it and does not. Nothing states whether 'id' is a sector identifier, a policy identifier, or a standard code, which is the one piece of information an agent needs to form a correct call. The discussion of the 'inputs' response field is helpful but describes output, not the input parameter.

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 purpose: retrieving the validation rules/guardrails that apply to a sector's emissions records. It explicitly separates this from compliance_policies (regulations), so an agent can distinguish it from the nearest sibling. It never identifies the resource by name (policies for a sector), so it stops just short of a fully unambiguous verb+resource 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?

It gives an explicit trigger (user asks which validation rules apply to a sector's emissions records) and an explicit exclusion with a named alternative (do not use for regulations; use compliance_policies). This is exactly the when/when-not/alternative structure that prevents miscalls.

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, destructiveHint=false and openWorldHint=false, so the safety profile needs no restating. The description adds one genuinely behavioral fact — that matching spans names, descriptions and field names — but says nothing about result ordering, whether limit is a hard cap or a default, or how the domain parameter narrows scope. Useful but thin beyond what annotations supply.

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 with no filler: the use condition and examples come first, the exclusion second, the matching scope and escalation path last. Every clause carries routing or behavioral information, and nothing is repeated from the 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?

For a read-only search over a closed-world catalog with no output schema, the description supplies enough to call it correctly: what to search for, what fields match, and where to go for the full record. The one material omission is the domain filter's meaning, which leaves a required-but-optional argument opaque.

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 0%, so the description must carry all three parameters. It partially covers q via the statement that matching spans names, descriptions and field names, but limit (1-500) and domain (max 100 chars) are never mentioned — notably, an agent cannot tell whether domain means sector, namespace, or tenant scoping. Compensation for the coverage gap is inadequate.

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 what the tool retrieves and at what granularity: the Open Footprint entity for a concept like "Scope 3 emissions", "facility" or "product footprint", matched against entity names, descriptions and field names. Concrete examples make the resource unambiguous, and it contrasts with ofp_entity's full definition. It never states the operation verb explicitly (search/retrieve) — that is carried by the tool name — which keeps it just short of a 5.

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

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

"Use this when you need..." gives the positive condition, "Do not use for emission factors or calculations" gives an explicit exclusion, and "use ofp_entity for the full definition" names the correct alternative for the adjacent case. All three routing signals an agent needs are present in two sentences.

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, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is fully covered. The description adds value by disclosing the shape of the returned content (classification, status, reference artifacts), but says nothing about error behavior for unknown ids or whether the lookup is exact-match.

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 front-loaded sentence with no wasted words. It is efficient, though its brevity is part of why parameter and usage detail are missing.

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 does sketch the return contents, which is helpful. But for a lookup tool keyed on an undocumented identifier, the omission of id format and not-found behavior leaves a meaningful 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?

There is one required parameter 'id' with 0% schema description coverage, and the description never clarifies what the id identifies (sector code, UUID, slug?) or its expected format. With the schema providing no documentation, the description should compensate but does not.

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 resource (one sector) and enumerates what it returns: classification, status, and reference artifacts. Combined with the title 'get sector', the verb+resource is clear, and the singular 'one sector' implicitly distinguishes it from the sibling list tool ofp_sectors, though it never names that sibling.

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?

'Use this when you need one sector's classification...' gives a usage condition, implying single-record lookup rather than listing. However, it never explicitly points to ofp_sectors for the list case or states prerequisites, so the when-not guidance 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 readOnly, idempotent, non-destructive, and closed-world, so the safety profile is covered. The description adds genuinely new context the annotations cannot: what 'implemented', 'planned', and 'placeholder' mean in this dataset, which shapes how an agent interprets results.

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

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

Two short sentences with the use case front-loaded and no filler. The second sentence is compact to the point of assuming the reader knows these terms attach to returned sector entries.

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 one optional enum parameter, no nested objects, and no output schema, the description covers the essential decision (when to call) and the interpretation of returned status values. Missing only the axis/result-shape linkage, which is minor for a single-parameter listing tool.

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

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

Schema coverage is 100%, so the single optional enum parameter is documented in structured data and the baseline is 3. The description does not mention the axis parameter or explain the esrs/sics distinction, and the schema's own enum text ('esrs (reporting groups) or sics (implementations)') stays terse despite the discussion of 'essential' status 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?

The description frames the tool as answering 'which industries Open Footprint covers' and 'whether a sector has a reference implementation,' which identifies the resource and scope clearly. The verb (list/enumerate) is only implied, and the singular sibling ofp_sector is never named, so an agent must infer the plural/singular split.

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 triggering conditions: a user asking about industry coverage or whether a sector is implemented. It stops short of exclusions or pointing to ofp_sector for detail on a single sector, which is the obvious alternative an agent would otherwise guess between.

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 readOnly, idempotent, non-destructive, closed-world behavior, so the safety profile is covered. The description adds real value beyond that with the caveat that codes carried by many fields are generic classifications and alignment to them asserts less than it appears — useful interpretive context. It still says nothing about what is returned or how many results to expect, which matters because there is 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?

Two sentences, front-loaded with the usage trigger, and no filler. The second sentence is terse to the point of being cryptic ('asserts less than it appears'), but it does carry a substantive caution rather than padding.

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?

Scored against a one-parameter, read-only lookup with full annotation coverage and full schema description coverage, the description supplies the usage trigger plus the one non-obvious caveat about generic classifications. The main remaining gap — return shape — is partly offset by that caveat, and the directional wording is already penalized under purpose clarity.

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 `code` parameter is documented with a concrete O-DEF example, so the schema carries the semantics. The description refers obliquely to 'a source-system field' and to codes without adding format, validation, or resolution rules beyond the schema. 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?

The title promises 'fields for a semantic code' (code in, fields out), but the description frames it in the opposite direction: 'you have a source-system field and need to find where it belongs.' The required parameter is a code, so the description leaves the lookup direction ambiguous and an agent cannot tell with certainty whether it resolves code→fields or field→code.

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?

There is a genuine use-case trigger ('when you have a source-system field'), which is more than nothing. But it never names alternatives such as ofp_semantics, semantic_query, or ofp_search_entities, and gives no condition for choosing this tool over them or any precondition for obtaining a valid O-DEF code.

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 this as a read-only, idempotent, closed-world lookup, so the safety profile is covered. The description adds genuinely non-obvious behavior: results with a high fieldCount are generic fallbacks, so callers should constrain maxFieldCount to get codes specific enough to align on. It still doesn't describe the shape or volume of the returned codes.

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, with the use case front-loaded and the parameter advice second. 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 one-optional-parameter read-only lookup, the definition covers the scenario and the parameter tradeoff, which is most of what an agent needs. However, with no output schema and no statement of what comes back (a list of codes? with what identifying fields?), the agent cannot predict the response it must map against.

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 0% and the single parameter has no description of its own, so the description must carry it — and it does, explaining that high fieldCount yields generic fallback codes and recommending a starting value of 10. The relationship between maxFieldCount and per-code fieldCount is inferable but not stated outright, keeping it short of 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?

The description names the concrete scenario (mapping fields from SAP, another ERP, or a supplier feed onto Open Footprint), which combined with the title makes clear this surfaces semantic codes for mapping. It stops short of a clean verb+resource statement of what the tool actually returns, and it never distinguishes itself from siblings like ofp_semantic_code or semantic_query.

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 triggering condition ("Use this when mapping fields from...") plus operational advice on setting maxFieldCount starting around 10. It lacks any when-not guidance or pointer to the closely named siblings, which is the main gap for an agent choosing among ofp_semantic_code, semantic_query, and semantic_templates.

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 this is a safe read (readOnlyHint=true, destructiveHint=false), but the description adds substantial depth beyond them: which checks run (structure, declared constraints, enum membership, calculations), which do not (undeclared ranges, unit coherence, referential integrity, factor provenance), and a hard reporting rule gated on sector_policy appearing in `checked`.

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 use case, then behavior, then caveats — a sensible order with no filler sentences. It is dense and packs several distinct obligations into one paragraph with backticked field names, which is efficient but slightly harder to scan than a structured list.

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?

Complexity is high (5 params, nested free-form payload, no output schema), and the description compensates well by naming the return fields an agent must read (`checked`, `checks_not_run`, `schema.coverage.constraintsDeclared`) and flagging `valid` as deprecated in favor of `schemaValid`. Only the `entity`/`domain` semantics remain 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 only 20%, so the description must carry the load. It clarifies `payload` and `sector` (guardrails) meaningfully, but `entity` and `domain` are never explained despite being required or present, leaving two of five parameters semantically undocumented anywhere.

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: check a JSON emissions/footprint record against the Open Footprint model or a sector's guardrails. An agent immediately knows what it does. It does not, however, distinguish itself from the similarly named sibling `validate_data`, which is the main ambiguity risk.

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 opens with a when-to-use condition tied to a concrete artifact (a JSON payload about emissions/footprint) and adds a when-not clause ('Do not use for general data-quality questions without a payload'). It also scopes sector behavior ('with a sector, its guardrails'), giving the agent enough to choose correctly.

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 (readOnly, non-destructive, closed-world, non-idempotent), so the description only needs to add context — and it does, disclosing a payment_required failure mode and the required agent behavior (inform the operator, do not retry). It stops short of describing result shape or what happens with an under-specified query, so it is not a full 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?

The usage condition is front-loaded and the paywall instruction is isolated in its own short paragraph, so both are easy to scan. Slight redundancy between the opening example list and the closing 'prefer a specific site, company or period' sentence, but nothing is wasted overall.

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 read-only tool with no output schema, the description covers selection, prerequisites, and the payment failure path, which is most of what an agent needs. It is still incomplete on the two things it uniquely must supply: the expected form of 'query' and the role of 'sessionId'.

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 0%, so the description must carry the parameter burden, and it largely does not. It hints at what 'query' should contain (site, company, period) but never says whether it is natural language or structured, and the second parameter 'sessionId' is never mentioned at all.

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 action and resource: answering a specific question about verified oil-and-gas emissions data, with concrete examples (methane, site/company/period) and standard names (PPDM, OGMP 2.0). It also explicitly contrasts itself with semantic_templates and with general climate questions, 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?

Gives an explicit when-to-use condition, an explicit when-not ('Do not use for general climate questions'), and a prerequisite/alternative ('Call semantic_templates first'). It also adds a query-refinement instruction ('Prefer a specific site, company or period') that steers call quality.

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, idempotentHint, openWorldHint=false and destructiveHint=false, so the safety profile is fully covered without the description. The description adds useful workflow context (it is a precursor to semantic_query) and domain scoping ('verified emissions data'), but says nothing about what the call actually returns, which matters because there is 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?

A single front-loaded sentence that opens with the trigger condition and closes with the next step. No redundant restatement of the tool name or 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 zero-argument, read-only discovery tool with full annotation coverage, the agent needs only to know why and when to call it, which the description supplies. The one gap is the absence of any hint about the return shape (a list of question patterns?), which is not covered by an output schema.

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 nothing for the description to disambiguate and no risk of misuse at call time. Baseline 4 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 states a concrete outcome — seeing which kinds of questions the verified emissions data can answer — which tells an agent this is a discovery/enumeration tool rather than a query tool. It is distinguishable from the sibling semantic_query, though it never uses the word 'templates' or says explicitly that it returns a list of question patterns (that information lives only in the title).

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 sequencing guidance ('before calling semantic_query') and names the alternative tool the agent should use next. It stops short of saying when not to use it, but for a zero-cost read-only discovery call the context is clear enough.

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 a safe read-only, non-destructive, closed-world operation, so safety context is covered. The description adds little beyond that: it never says what validation produces (pass/fail, error list, severity), how strict validation is, or what version mismatches do. The masterData/referenceData restriction merely restates the schema enum.

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

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

Two short sentences with no filler, but 'call list_standards first' appears twice, making the second line redundant. It also opens with usage guidance instead of a front-loaded statement of what the tool does.

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

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

For a tool with five parameters, a nested object payload, and no output schema, the description omits what the data object must look like, what version and entityType control, and what a successful versus failed validation looks like. Routing guidance is complete, but invocation-critical detail 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 only 20% across five parameters, so the description must compensate and largely does not. It implies the standard name must come from list_standards, but says nothing about version, entityType, or the shape/requirements of the nested data payload, and its category note duplicates the schema enum text.

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

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

The first sentence states what the tool does (a payload is 'checked against a standard other than Open Footprint') and immediately names the scoping condition. It cleanly distinguishes itself from ofp_validate, though it leads with usage rather than a plain statement of purpose.

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 when-to-use (non-Open Footprint standards), explicit alternative (ofp_validate for Open Footprint payloads), and an explicit prerequisite (call list_standards first to see supported standards). Nothing about tool routing 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.