CompanyGraph

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the agent knows this is a safe, deterministic local lookup; the bar for extra disclosure is low. The description adds 'No input' and 'use this once', which is minor behavioral context, but most of the text re-states what the output schema already 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?

Front-loaded with the core purpose, then usage, then return shape. The sentences are dense and mostly earn their place, though the trailing enumeration of returned fields overlaps with the output schema and adds bulk.

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 and annotations covering safety, the description is complete enough to call correctly. It redundantly narrates return fields, but nothing an agent needs to invoke this zero-input tool 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?

This is a zero-parameter tool, so the baseline is 4. The description reinforces 'No input', which is consistent with the empty schema and leaves nothing ambiguous.

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 opening 'What a refused call looks like' names the resource (refusal/error shape) and the tool is clearly a schema-describing lookup. The line 'A tool's output schema covers its answers only' implicitly separates this from describe_schema, though it never names the sibling outright, so an agent must infer the boundary.

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

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

Explicit guidance: 'use this once, to branch on refusals or validate them' tells the agent both the purpose (branch/validate) and a usage constraint (once, not repeatedly). It frames the contrast with normal answer-schema inspection but stops short of naming describe_schema as the alternative.

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 and openWorldHint=false, so safety is covered. The description adds real behavioral context: the result is unpaged ('Not paged') and includes `forms` and `reading` fields that explain every term. It stops short of describing volume or shape of the returned lists.

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?

Very dense and front-loaded: purpose first, then routing, then parameter semantics, then return note. Every clause earns its place, though the telegraphic, comma-spliced style costs a little readability.

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 needn't be re-explained, yet the description still notes the lists, `forms`, and `reading`. Combined with clear param semantics and annotation-covered safety, an agent has what it needs, with only the value formats for `type`/`via` left 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?

Schema description coverage is 0%, so the description must carry the load, and it does: `type` narrows every list, `direction` gives one side of relations and needs `type`, `via` scopes relations and enums. It covers all three params meaningfully, though it doesn't state the accepted value format for `type` or `via`.

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 the specific resource (relations declared between types) and enumerates what it covers: references with form/cardinality, ownership, enums, joins, list kinds. It explicitly distinguishes itself from the sibling describe_schema, 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?

States the use case ('for a diagram or audit') and names the alternative with its selecting condition ('for one type's full schema use describe_schema'). It also flags the dependency that `direction` requires `type`, which is usage guidance beyond the schema.

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 safe-read profile is covered. The description adds genuinely new behavioral context: an unknown rule number is refused and the known numbers are listed, which tells the agent how failure is surfaced.

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

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

Three sentences, front-loaded with the entity-type scope and input requirement, with no filler. It is dense rather than padded, though the parenthetical sibling references interrupt the flow slightly.

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 an output schema, the description covers scope, input source, and error behavior. Since an output schema exists it needn't enumerate return fields, so the listed return values are redundant but harmless.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning beyond the schema — it states the value is a number sourced from list_rules and that it is accepted in either case, which the schema does not mention. That case-insensitivity detail is a meaningful parameter behavior enhancement.

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 identifies the resource precisely — one vocabulary convention of type `rule` — and explicitly distinguishes it from a company's own rule, naming sibling entity tools. The verb is only implied by the name rather than stated, so it falls just short of a crisp verb+resource pairing.

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 tells the agent the input must be a number drawn from list_rules (e.g. R9) and points to list_entities/get_entity for the entity distinction, giving clear context for when this tool applies. It does not spell out exclusions or an explicit alternative when the input is not a rule number, but the sourcing requirement covers most selection ambiguity.

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 mainly return-shape detail (url, sections, relations), which duplicates the output schema rather than disclosing new behavioral traits, so a baseline 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?

Three compact sentences with purpose front-loaded, followed by when-to-use and input/return summary. Dense but every clause carries weight; only a minor lack of readability in the phrasing.

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 description still routes to describe_relations. Combined with full parameter coverage and read-only annotations, it is complete enough for an agent to call it correctly.

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

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

Schema coverage is 100% and the single `type` parameter is already documented in the schema ('A type name from list_types, such as skill'). The description merely restates 'Input: `type`', adding no new syntax or format meaning, so the baseline 3 holds.

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: it returns one type's schema, decomposed into 'sections as written' and 'declared relations as data'. It partially differentiates from siblings by naming describe_relations for the whole-vocabulary case, though the jargon ('sections as written') is slightly opaque.

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

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

Explicitly states when to use it ('Use to learn what an entity of the type may hold') and names the alternative ('for the whole vocabulary use describe_relations'). No exclusions or prerequisites are given, but the routing guidance is clear.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds a real behavioral constraint ('takes no name: search with match "name" finds the id') plus the returned shape; the return fields are partly redundant with the output schema, keeping this from 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 front-loaded sentences, purpose first, alternative second, input/return details last. Every clause carries information; nothing is 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?

For a single-parameter read tool with annotations and an output schema, the description covers everything the agent needs: what it returns, how to obtain the id, the name-vs-id caveat, and the alternative tool. No material gaps.

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%, so the description must carry the parameter burden, and it does: `id` is described as an entity id or address, with concrete sources (search, list_entities, references). It stops short of format/syntax detail for the id string.

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: retrieving one entity's page 'as written' (the raw source). It explicitly distinguishes itself from the sibling get_entity ('for structured fields and references use get_entity'), so an agent can route correctly without opening either schema.

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

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

Gives explicit when-to-use ('to quote or display the source') and when-not ('for structured fields and references use get_entity'), and names the alternative. It also tells the agent where valid input comes from (search, list_entities, any reference).

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 that attributes are verbatim and sketches the return grouping, but says nothing about pagination limits beyond the schema or about failure modes for a nonexistent skill.

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

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

Four short sentences, each doing distinct work: resource, usage, inputs, outputs. Slightly odd ordering (output described before inputs are fully explained), but no filler.

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

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

With an output schema present the return-shape sentence is partly redundant, yet the description still covers input forms, grouping semantics and the level/evidence join path. Adequate for a read-only graph query; only the absence of routing guidance keeps it from 5.

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 defaults, clamping and cursor semantics, so the schema carries the parameter burden. The description merely restates the parameter names ('Input: skill... optional limit, cursor'), adding no 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?

States a specific retrieval: 'every edge into one skill, grouped by the type of the page that drew it', which is a concrete verb+resource and scope. It doesn't name or contrast against any sibling (list_references, describe_relations), so it falls short of the 5 benchmark for 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?

'Use to check a claimed skill against its evidence' gives an implied use case but no when-not conditions and no named alternatives among the many list_*/describe_* siblings. The agent can infer intent but must guess at boundaries.

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 and openWorldHint; the description adds real behavioral detail beyond them: ambiguous names are refused with candidate ids, reference lists are capped at 50 edges, referenceCounts supplies totals, and list_references is the escape hatch for the rest. That is exactly the extra context an agent needs to interpret a truncated result.

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?

Tight and front-loaded, with purpose first and the fetch contrast immediately after; no sentence is pure filler. The telegraphic em-dash style is dense to the point of being slightly clipped, but it earns its space.

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, yet the description still sketches the shape ('returns `entity`, by id') and covers the ambiguity refusal and the 50-edge truncation with its companion tool. Complete for the core call; a note on whether id/name/type can be combined would close the last 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?

At 67% schema coverage the schema already documents id and name, but the description adds the id-or-address alternative and the type+name pairing for canonical-name lookup, plus the behavioral consequence of an ambiguous name. The bare `type` parameter is still not given standalone 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 concrete verb+resource: fetch 'one entity as structured data: fields, sections, tables, references both ways.' It also names a specific sibling (fetch) it must not be confused with, so an agent can separate the structured view from the rendered page 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?

Explicitly gives the selecting condition ('Use to reason over one; for its page as written use fetch') and names the alternative, which is strong routing. It doesn't cover when to prefer list_entities or search instead, so it falls short of full when/when-not coverage.

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 bar is lower; the description adds meaningful context beyond that by stating 'This server runs none of them', removing any impression that listing the checks executes them. It also discloses the return shape, including the failure/note distinction, which annotations do not cover.

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

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

Purpose and the no-execution caveat come first, with return details last. It is slightly verbose enumerating the returned fields (`name`, `rule`, `title`, `reports`, `ranBy`) when an output schema exists, but nothing is wasted or buried.

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

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

With an output schema present, the description needn't detail returns, and its field enumeration is redundant but harmless. It covers what the tool is, that it takes no input, and that nothing is executed — enough for an agent to call it correctly; the main gap is the absence of explicit sibling routing.

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 still explicitly says 'No input', confirming the empty schema rather than leaving an agent to infer 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 names a specific resource (the checks) and its provenance (the checker release the server was built with), and clarifies the checks belong to the model's gate rather than this server. It distinguishes the tool from siblings like list_rules and list_types, though the phrase 'the model's own gate' is somewhat opaque without prior context.

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 to see which rules a script enforces and which are left to a reader' gives a concrete scenario, but it never names an alternative (e.g. describe_rule or list_rules) or states when a different listing tool is the right choice. Usage is implied rather than routed.

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 safety is covered. The description adds real behavioral context beyond that: the return contains `entities` with `fields` and a `page`, and the caller should loop on `page.nextCursor` while `page.hasMore` — a pagination contract not implied by the annotations. It says nothing about auth needs or rate limits, which are low-stakes for a read.

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 tightly packed sentences with no filler, and the core behavior plus pagination contract are front-loaded. The telegraphic, fragment-heavy style occasionally costs clarity, but nothing is wasted and it is appropriately sized for a 9-parameter tool.

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

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

With an output schema present, the description need not explain return values, yet it still summarizes the response and the pagination loop, and all 9 parameters are fully documented in the schema. It covers sibling routing ('use search'), ordering defaults, and cursor usage; only permission scope and ties to specific siblings like get_entity are unaddressed.

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

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

Schema description coverage is 100%, so the schema already explains every parameter (on, by, order, where, limit, cursor, fields) in detail. The description merely re-lists the parameter names without adding format, defaults, or interaction rules beyond what the schema states, 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 the specific resource (entities) and the shape of the return (short facts from frontmatter, in a defined order), so the agent knows this is a listing/browse operation rather than a lookup. It also implicitly distinguishes itself from `search` by directing word-based retrieval elsewhere, though it does not name other list siblings (list_types, list_rules, list_checks).

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 conditions: use to browse, use for what runs on a date, what came last, or what has a value. It explicitly names the alternative for a different need ('to find by words use search'), which is real routing guidance. It stops short of stating exclusions or prerequisites (e.g., permission scope, when get_entity is preferable for a single item).

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 the pagination model (limit/cursor, page.nextCursor), the constraint that direction requires entity, and the shape of returned edges. These are genuine behavioral disclosures beyond the annotations, though the output schema already carries the return structure.

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 resource and purpose before the parameter walkthrough. The parameter enumeration is dense but each clause carries distinct semantics; there is little 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 read-only, six-parameter filtered list with an output schema, the description covers purpose, filtering semantics, the entity/direction dependency, and pagination. Since the output schema exists, the redundant return-value sentence is harmless rather than necessary, and no critical invocation 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 coverage is only 33% (entity, direction, via, type lack schema descriptions), so the description does real work: it defines entity as an id or address, constrains direction to out/in/both and notes it needs entity, and explains that type means the far end's type, or either end's when entity is absent. That conditional semantics meaningfully exceeds 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 opening sentence identifies the resource ('the model's edges') and its treatment ('filtered and paged'), and the second sentence clarifies the intent to inspect relations without pulling whole entities, implicitly contrasting with get_entity/list_entities. It never names the sibling tools directly, so differentiation is inferential rather than explicit, keeping 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 a clear use case ('inspect one entity's relations or one kind of reference without taking whole entities'), which tells the agent when this is preferable to fetching full entities. There are no explicit exclusions against the other relation-oriented siblings (describe_relations, describe_schema), so it stops short of full 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 declare readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds real context beyond that: it takes no input and it returns tagline, the file's url, and rules objects with rule/title/part, plus routes single-rule lookups to describe_rule. Minor gap only in not stating anything about pagination or caching of the source file.

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

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

Dense but front-loaded: purpose first, then usage trigger, then alternatives, then return shape. Every sentence carries information, though the middle clauses are somewhat packed and could be split for readability.

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-input, read-only list tool with an output schema, the description covers purpose, usage trigger, alternatives, and return shape. Nothing an agent needs to select or 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?

Zero parameters, so the baseline is 4. The description still explicitly states 'No input,' confirming the empty schema rather than leaving it 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?

States a specific resource (the vocabulary's conventions/R-rules from CONVENTIONS.md) and its scope (R0 onwards), and explicitly distinguishes itself from sibling behavior by noting that company-specific rules are entities handled by list_entities/get_entity. An agent can tell it apart from list_entities and describe_rule 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?

Gives an explicit trigger ('Use to resolve a number a schema or refusal cites, such as R9') and names the alternatives for the adjacent case (company rules → list_entities and get_entity). The condition selecting this tool versus its siblings 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?

Annotations already declare readOnlyHint=true and openWorldHint=false, so the agent knows this is a safe, closed-world read. The description adds 'No input' and enumerates return fields, which is useful but mostly restates structured data rather than disclosing traits like ordering, size limits, or 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?

Three short sentences, front-loaded with what it returns, then when to use it, then the return shape. No filler and no 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 no-argument, read-only discovery tool with an output schema already defined, the description supplies everything an agent needs: scope, call ordering, and a preview of the returned fields. Nothing material is missing.

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

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

The tool takes zero parameters, so the baseline is 4. The description's 'No input' statement correctly matches the empty schema, though it adds nothing beyond that confirmation.

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 resource precisely ('every type the model's schemas declare'), which cleanly separates it from siblings like list_entities, list_rules, and list_references. The opening is a fragment rather than an explicit verb+resource, but the scope is 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?

'Use first, to learn which types exist before listing or describing one' gives explicit ordering guidance and a rationale, telling the agent to call this before describe_schema or the list_* siblings. It stops short of naming a specific alternative tool or stating when not to use it.

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 read-only and closed-world safety, and the description adds genuinely non-obvious behavior: stemming in 'words' mode, case-insensitive substring matching in 'text' mode, the fields scanned (name, tagline, fields, sections, cells), and result ordering (name matches first, then a listing). It omits cost, rate limits, or performance characteristics, but for a read-only search this is solid 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?

A single dense paragraph that front-loads the core action, then semantics, then return shape, with no filler sentences. The heavy use of backticked tokens makes it information-rich but slightly hard to scan.

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 the description did not need to enumerate return fields, yet it does so briefly and harmlessly. Required parameter 'query' is left unexplained but is self-evident. Coverage of modes, filters, and pagination is sufficient for correct invocation.

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

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

Schema coverage is only 50% and the enum on 'match' has no per-value documentation, so the description carries real weight: it defines the semantics of all three match modes and names the optional type/owner/limit/cursor controls. The schema already documents limit clamping and cursor usage, so the description correctly avoids duplicating those.

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 concrete verb and resource ('Find entities') plus the three matching modes, so the core purpose is unambiguous. It does not, however, distinguish itself from siblings such as list_entities, get_entity, or find_evidence, so an agent must infer the boundary on its own.

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

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

Usage is implied rather than stated: the description explains when each match mode applies and which is the default, which effectively guides mode selection. It offers no guidance on when to reach for this tool instead of list_entities or find_evidence, and no prerequisites or exclusions are given.

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