CompanyGraph

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

With no annotations, the description carries the behavioral burden. It discloses that the tool takes no input, returns a well-defined structure, and is intended for a single use to branch on or validate refusals. It could be more explicit about being side-effect free, but for an introspection tool this is adequate.

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 compact and front-loads the purpose before details. The final sentence is dense, but every clause adds information about the returned structure; no filler is present.

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-input introspection tool with an output schema, the description is complete: it covers why to call it, what it returns, and how the refusal structure is organized. It also explains the key gap an agent might otherwise miss — that the tool's output schema covers only answers, not refusals.

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 are zero parameters, so there is no schema/description gap, and the description reinforces this with 'No input.' The baseline of 4 applies because no parameter documentation is needed.

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 opens with 'What a refused call looks like' and then specifies concrete outputs (`errors`, `code`, `schema`). This clearly distinguishes it from sibling introspection tools like `describe_schema`, `describe_rule`, and `describe_relations`, which cover different aspects of the API.

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 says 'use this once, to branch on refusals or validate them', giving a clear invocation condition. It does not name alternatives or state when not to use it, but the refusal-oriented purpose makes the guidance sufficient for correct selection.

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

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

With no annotations, the description takes on the full burden. It discloses return shape ('Returns those lists'), explains output terms ('with `forms` and `reading` explaining every term'), and states pagination behavior ('Not paged'). It also reveals a parameter dependency ('needs `type`'). It does not explicitly state read-only/safety, but the verb 'describe' and introspection-focused phrasing make that highly implicit.

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 cover purpose, usage, parameters, return format, and pagination without waste. The purpose is front-loaded and the alternative tool is named immediately. Each clause earns its place, and the dense style remains readable.

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 three optional interdependent parameters and no required inputs, the description covers all essential bases: what it returns, how to filter, when to use it instead of a sibling, and the output schema is provided separately. The 'Not paged' note removes a common ambiguity. Nothing needed for correct invocation is missing.

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

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

Schema description coverage is 0%, so the description must compensate, and it does. Every parameter is explained: `type` narrows every list, `direction`'s enum values are listed with its dependency on `type`, and `via` filters relations and enums. This adds meaning far beyond the raw 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 defines the tool's output as 'what the schemas declare between types' with specific artifacts (references, ownership, enums, joins, list kinds), making the resource and scope unmistakable. It also explicitly contrasts with describe_schema, telling the agent exactly when this tool is not the right one. This qualifies as a specific verb+resource with 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?

It explicitly says 'Use for a diagram or audit' and points to describe_schema as the alternative for one type's full schema. This gives clear context for when to invoke this tool and when to turn elsewhere. The optional parameter explanations further guide usage for narrowing results.

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?

No annotations are provided, so the description carries the behavioral burden. It discloses that unknown rule numbers are refused with known ones listed, that input is case-insensitive, and that the response contains the rule text as written plus file URL. This is meaningful behavioral detail, though it does not discuss permissions or side effects, which are less relevant for a read-style tool.

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 no filler. The core purpose is front-loaded, the parameter guidance is precise, and the error behavior earns its place. Every sentence adds useful 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 single-parameter lookup tool with an output schema present, the description is complete. It supplies the argument source, case handling, error behavior, and return fields. Nothing needed to call this tool safely and effectively is missing.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value beyond the schema by noting case-insensitivity, the validation/refusal behavior, and the explicit linkage to list_rules as the source of valid rule numbers. These extras help an agent invoke the tool correctly.

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

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

The description clearly identifies the tool as returning one rule as written, with a single resource type and the exact return fields. It is readily distinguishable from sibling list_rules, describe_schema, and describe_relations. The reference to 'from list_rules' anchors the argument source without ambiguity.

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

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

The description explains the required input, that it must be a rule number from list_rules, and that values are case-insensitive. It also describes the refusal behavior for unknown numbers. It does not explicitly name alternative tools or when-not-to-use conditions, but the list_rules prerequisite provides clear usage context.

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

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

With no annotations, the description carries the full burden, and it delivers: it specifies the return fields (url, sections, relations) and even characterizes the data nuance ('sections as written' and 'declared relations as data'). No side effects or contradictions are present.

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 tight sentences: it front-loads the core purpose, gives the alternative, then lists input and output. Every clause earns its place with no filler.

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

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

For a one-parameter read-oriented tool with an output schema present, the description provides all necessary context: purpose, alternative, parameter pointer, and return composition. Nothing an agent needs to invoke it correctly is missing.

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

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

The single parameter is already fully documented in the schema ('A type name from list_types, such as skill'), so the description's 'Input: type' adds no new semantic value. Baseline 3 is appropriate because the schema covers the parameter completely.

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 clearly states the tool exposes one type's schema, and explicitly separates it from describe_relations ('for the whole vocabulary use describe_relations'). An agent can distinguish this tool from its siblings immediately.

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 ('Use to learn what an entity of the type may hold') and names the alternative for the broader vocabulary case. This is clear routing guidance with minimal 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?

No annotations are present, so the description carries the behavioral burden. It discloses the return fields, that text is Markdown source, and that no name parameter exists. It does not discuss error cases or auth, but for a simple read/fetch operation this is adequate.

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 compact and every sentence earns its place: purpose, usage distinction, input provenance, output shape, and a critical constraint about name. It is front-loaded with the core purpose.

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 low-complexity tool with one required parameter and an output schema, the description covers the essential invocation context: when to use it, what to pass, what comes back, and how it differs from the relevant sibling. No significant information 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 schema only defines id as a string, with 0% description coverage. The description meaningfully compensates by explaining the id's provenance (from search, list_entities, or any reference) and explicitly stating that name is not a valid parameter, preventing a common misuse.

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 clearly identifies the tool as retrieving 'one entity's page as written' and explicitly contrasts it with get_entity for structured fields and references. This distinguishes it from siblings and states the resource being operated on.

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 provides explicit routing guidance: use this tool to quote or display source, use get_entity for structured fields and references. It also tells the agent where ids come from (search, list_entities, or any reference) and warns that name input is not accepted.

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

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

With no annotations, the description carries the behavioral disclosure burden. It discloses aggregation/grouping behavior, the shape of results (skill, evidence, page), how profile claims vs evidence rows are represented, and that attributes are returned verbatim. This goes beyond the bare operation, though it doesn't address safety or side effects.

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 compact and front-loaded: purpose, use case, input, output, and data representation each earn their place in a short paragraph. There is no filler or repetition of schema details.

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 one required parameter, an output schema, and clear pagination semantics already documented in the schema, the description is sufficient. It covers the main use case, result shape, grouping behavior, and data-source semantics; the only minor gap is explaining what 'page' means beyond the 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?

Schema coverage is 100% and the schema already documents skill, limit, and cursor thoroughly, including clamping and cursor reuse. The description only restates that skill is an id or canonical name and that limit/cursor are optional, 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?

The description states the operation in concrete terms: it returns every edge into one skill, grouped by the page type that drew the edge, and it frames the intended use ('check a claimed skill against its evidence'). This is specific enough to distinguish it from generic siblings like search or fetch, though the domain jargon ('edge', 'page') is not unpacked.

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 use case: 'Use to check a claimed skill against its evidence.' It does not name alternatives or exclusion conditions, so it stops short of a 5, but the guidance is clear enough for an agent to know when this tool is appropriate.

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?

No annotations are provided, so the description carries the full burden. It discloses the return value ('entity'), the 50-edge cap per reference list, that referenceCounts gives totals, and that list_references holds the rest. It also mentions refusal behavior for ambiguous names. This is comprehensive for a read operation.

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 concise sentences, front-loaded with purpose, then usage, then behavioral details. No redundant phrasing; every sentence adds value.

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

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

With an output schema present, the return format is covered. The description addresses input selection, ambiguity handling, and pagination limits, leaving no critical gaps for a tool of this complexity (3 optional params, no nested objects).

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 covers id and name descriptions but not type (67% coverage). The description adds the relationship: 'Input: id, or type and name', clarifying that id alone or type+name together are valid. This compensates for the missing type description and adds 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?

Description states the tool returns one entity as structured data (fields, sections, tables, references both ways), a specific verb and resource. It distinguishes itself from fetch (page as written) and list_references (for more edges), making its scope unambiguous.

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

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

Explicitly says 'Use to reason over an entity; for its page as written use fetch', naming the alternative and when to prefer it. Also notes that an ambiguous name is refused with candidate ids, guiding the agent on valid input patterns.

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

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

With no annotations, the description carries the behavioral disclosure burden. It does well by stating there is no input, describing the returned fields, and explicitly noting that this tool returns only a list with no verdict because the server runs none of the checks. This conveys important non-obvious behavior beyond a simple enumeration.

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: what the resource is, when to use it, and what it returns. The key behavioral caveat ('no verdict') is saved for the end but is clearly stated without 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 zero-parameter list tool with an output schema, the description is complete. It explains the provenance, the practical use, the return shape, and the critical limitation that no checks are actually run by this server. Nothing essential 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?

There are zero parameters, so the schema provides no meaningful parameter semantics. The description explicitly confirms 'No input', which matches the empty schema and leaves no ambiguity for the agent.

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 clearly identifies the resource: the checks that the model's own gate runs, sourced from the checker release of the server. It also explains the intended use—seeing which rules a script enforces—which separates it from a generic list. It does not explicitly name a sibling alternative, but the content is specific enough to avoid confusion.

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

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

The description gives a clear usage context: use this to see which rules a script enforces and which are left to a reader. It does not provide explicit exclusions or name alternative tools for other cases, but the 'Use to...' phrasing gives practical direction.

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

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

With no annotations provided, the description carries the full burden and does well: it discloses the returned fields, default and maximum limit, owner filtering, and the pagination contract via nextCursor and hasMore. This gives an agent enough behavioral context to call and iterate safely.

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 compact and front-loaded, with the core purpose stated first, followed by usage routing and then input/output/pagination details. Every sentence adds value and nothing is redundant.

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?

Despite having no annotations, this description covers what the tool does, when to choose it over search, all inputs, the output shape, and the pagination loop. An agent has everything it needs to invoke the tool correctly and process the results.

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 75%, covering owner, limit, and cursor. The description mostly restates the schema's meaning for type and owner, but it adds useful context about limit's default and paging flow. Since the schema already documents most parameters, the baseline of 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 description uses a specific verb and resource: lists entities of one type for browsing, and explicitly contrasts itself with search for finding by words or name. This makes it easily distinguishable from the sibling tools without needing to open 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 clearly states when to use this tool ('Use to browse a type') and routes name/word-based lookups to search. It could more explicitly contrast with get_entity or list_types, but the browsing context and search alternative provide solid practical 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?

With no annotations provided, the description carries the behavioral disclosure burden. It discloses filtering/paging behavior and the exact return shape (edges with from, via, to, attrs, and page). The 'inspect' framing implies a read-only operation, though this is not stated explicitly.

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 compact and efficiently structured: core behavior first, then parameter semantics, then return shape. Every sentence contributes necessary information without redundancy.

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

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

For a 6-parameter, annotation-free paginated tool, the description plus schema covers filtering options, dependencies, and response structure. The main gap is the lack of a precise definition for 'via', and read-only behavior is only implied.

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 input schema only documents limit and cursor, leaving 4 parameters undocumented. The description compensates by explaining entity, direction, direction's dependency on entity, and type's conditional meaning. 'via' is named but its semantics are somewhat implied rather than fully explained.

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 clearly identifies the tool's purpose: listing the model's edges/references, with filtering and pagination. It also differentiates itself from fetching whole entities, which distinguishes it from get_entity/list_entities.

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

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

The description gives an explicit use case: inspect one entity's relations or one kind of reference without pulling whole entities. It doesn't name sibling tools or explicitly state when not to use it, but the usage 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?

With no annotations, the description carries the burden, and it discloses that there is no input, where the data comes from, and the return shape (tagline, URL, and rules with rule/title/part). It does not mention error/ordering/freshness behavior, but this is a simple zero-input read tool.

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 a compact two-sentence definition that front-loads the resource and use case, then gives output and alternative in the same breath. Every clause earns its place.

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

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

For a zero-input list operation with an output schema, the description supplies purpose, usage trigger, output fields, and the relevant sibling. There is no meaningful missing context 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?

There are zero parameters and 100% schema coverage, so the baseline is 4. The description adds 'No input', which confirms there is nothing more for an agent to supply.

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

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

The description identifies the resource ('the rules the model is held to, from the CONVENTIONS.md') and the exact use case ('resolve a rule number that a schema or a refusal cites, such as R9'). It also distinguishes itself from describe_rule by noting that describe_rule gives one rule's text.

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 for use ('rule number a schema or refusal cites') and names the sibling alternative describe_rule for the full text of one rule. It does not explicitly state when not to use list_rules, but the context is sufficient.

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

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

With no annotations provided, the description carries the full burden. It clearly states the tool takes no input and returns a specific structure: `types`, each with `type`, `name`, `tagline`, `owner`, and `count`. It also explains the meaning of `owner` (the type it nests under, or null) and `count` (entities it holds), which is valuable behavioral context beyond a bare list.

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 compact and front-loaded: it states the purpose, the usage directive, the no-input fact, and the return shape in three sentences. Every sentence earns its place, and there is no redundant or filler content.

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

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

For a zero-input discovery tool, the description is complete. It explains what the tool returns, the fields in each item, and when to use it. The output schema exists, so the description need not repeat return-value details beyond what is useful for selection. Nothing an agent needs to call it correctly is missing.

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

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

The tool has zero parameters, and the schema is an empty object. The description explicitly says 'No input,' which fully resolves parameter semantics. The baseline for 0 params is 4, and the description adds clarity by confirming no arguments are needed.

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 ('list') and resource ('types'), and immediately clarifies that it returns every type declared by the model's schemas. It also distinguishes itself from sibling tools like describe_schema and list_entities by focusing on the type-level catalog rather than schema details or entity instances.

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

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

The description explicitly says 'Use first, to learn which types exist before listing or describing one.' This gives a clear when-to-use directive and implies it is the entry point before other tools like describe_schema or list_entities. It also notes there is no input, which prevents an agent from trying to pass parameters.

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

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

With no annotations provided, the description carries the full behavioral burden and does so well. It discloses the default match mode, the exact substring scope ('name, tagline, fields, sections and table cells'), case-insensitivity, the exact-name behavior, the response shape, and the non-ranking ordering.

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 dense but efficient: every sentence adds a distinct fact, the most important semantics are front-loaded, and the 'not a ranking' clarification is placed at the end without repeating schema details. No filler or tautology.

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 six-parameter tool with an output schema, the description covers defaults, matching semantics, optional parameters, pagination hints, and return fields. It is missing only the valid values or format for 'type' and explicit routing to sibling tools, which keeps it from a perfect score.

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%, so the description must compensate, and it adds genuine meaning to the query and match parameters: the 'text' mode's search scope and the 'name' mode's canonical exactness. It even explains the return fields. The only notable gap is that 'type' is left without semantics or allowed values in both the schema and description.

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 ('Find') and resource ('entities'), and precisely distinguishes the two match modes: case-insensitive substring over named fields vs exact canonical name. It also notes the ordering ('by type then name, not a ranking'), which helps separate it from generic listing tools.

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

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

The description clearly implies when to use it: when you need to find entities by words or by an exact name. However, it never names any sibling tool such as list_entities or get_entity, nor does it state when not to use it, leaving alternatives and exclusions to inference.

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