Family Office Knowledge Graph

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 useful behavioral context: it specifies the exact fields returned and the optional versioning behavior. It does not contradict annotations and supplements them with return-content details.

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 single, front-loaded sentence with no filler. It leads with the resource and scope, lists the key returned fields, and notes the optional version—every word 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?

Given the low complexity (2 params, 1 required) and the presence of an output schema, the description is adequate. It explains what the tool returns and the optional versioning, and annotations cover safety. It does not describe error cases or not-found behavior, but that is not critical for a read-only retrieval 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 description coverage is 100%, so both parameters are already fully documented. The description adds minimal extra meaning: it mentions 'named version' which aligns with the schema's 'version' parameter, but does not clarify identifier formats beyond the schema. Baseline 3 is appropriate since the schema carries the semantic weight.

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 'get' and resource 'Family Office Record', and scopes it to 'one identifier'. It enumerates the returned fields (value, source_url, read_by, state) and mentions an optional named version, which clearly differentiates it from the sibling list/resolve tools that operate on collections or resolve identifiers.

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 implies when to use it (when you have a single identifier and want the full record), but it does not explicitly name alternatives or state when not to use it. Sibling tools like list_nodes and resolve_family_office are not referenced, leaving the agent to infer the distinction from 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is fully covered. The description adds the behavioral detail that results include each name with its source, which is useful but not extensive. It does not describe pagination, ordering, or what happens when no aliases exist, but the output schema likely covers 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?

The description is a single sentence that front-loads the core purpose and enumerates the included name types. It is concise and every phrase earns its place, though it could be slightly more explicit about usage context.

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 list tool with one parameter, a complete output schema, and annotations covering safety, the description is nearly sufficient. The only gap is the lack of explicit guidance on when to choose this over sibling tools like get_record or list_nodes, but the tool's simplicity and schema coverage keep the gap small.

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 documents the identifier parameter thoroughly, including accepted forms (record id, LEI, legal name, alias, register identifier) and case-insensitivity. The description adds the semantic context that the identifier refers to 'one identifier' and that aliases are names carried by the record, but it does not add much 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 verb ('list') and resource ('aliases for a record identifier'), and clarifies the scope by enumerating the kinds of names included (legal name, register names, other names) with their sources. It is clear enough to distinguish from siblings like get_record or list_nodes, though it does not explicitly name a sibling to contrast with.

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 implies usage: call this when you need all names associated with a record identifier. It does not explicitly state when to use an alternative, such as get_record for a single canonical record or list_nodes for broader traversal. The identifier parameter description adds context about what can be passed, but no explicit when/when-not guidance is given.

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

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

Beyond the annotations (read-only, idempotent, non-destructive), the description discloses ordering (oldest first), filtering (optionally since a date), and pagination (paged by cursor). It also notes events are 'URL'd', hinting at output structure. These are valuable behavioral traits not covered by annotations, so the description adds meaningful 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?

A single, compact sentence packs in the core purpose, event types, ordering, optional filter, and pagination. Every phrase adds value and the key scoping ('one record') is front-loaded. No fluff or redundancy.

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

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

For a read-only list tool with an output schema and solid annotations, the description covers the essential operational details: scope, event categories, ordering, optional date filter, and pagination. The required identifier is implied by 'one record' and documented in the schema. Minor gaps like limit explanation are covered by schema defaults, so the description is sufficiently complete.

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 75% (since, cursor, identifier have descriptions). The description echoes 'optionally since a date' and mentions pagination, but does not add new meaning beyond what the schema already provides for the since and cursor parameters. It adds no detail on limit or identifier. With high coverage, 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 states a specific verb ('list') and resource ('events on one record'), with concrete event types and ordering ('oldest first'). It is clearly distinguished from sibling tools by its focus on events, even without naming alternatives. The scope 'one record' adds clarity.

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 what the tool does but gives no guidance on when to use it versus alternatives like get_record or list_aliases. It mentions 'optionally since a date' as an option, but does not frame the selection context or any exclusions. An agent would have to infer when this tool is the right choice.

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. The description adds useful behavioral context by explaining that record counts are read from each node's index and listing the fields returned. It does not mention pagination or performance characteristics, but the safety profile is well covered.

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 single sentence with no wasted words, and it front-loads the core claim about listing nodes. The use of en-dashes and domain jargon like 'node door' and 'as-of' slightly reduces clarity, but the text is appropriately compact.

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 gives enough context about what the tool returns and how counts are derived. It does not explain 'node door' or 'as-of', but these are likely defined by the output schema or domain context, making the description largely complete.

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 tool has 0 parameters contaminants, so the schema covers the input surface completely. The baseline of 4 applies, and the description does not need to add parameter semantics.

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 lists graph nodes, one per jurisdiction, and includes record counts, node door, and as-of. This is a specific verb+resource combination. It does not explicitly distinguish from sibling tools, which prevents 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?

No guidance is provided about when to use this tool versus siblings like get_record, list_aliases, or list_events_since. The context implies it is the way to enumerate nodes, but there is no explicit when-to-use or alternative routing.

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

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

Annotations already establish readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so no safety contradiction exists. The description adds that resolution may return each record with its serving node, which is useful context, but it does not disclose match behavior, multiplicity, or failure semantics beyond that.

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?

One dense, front-loaded sentence with no filler. Every phrase earns its place by defining the action, acceptable inputs, and the return shape.

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-only lookup with full schema coverage and an output schema present, the description is nearly sufficient. It is missing only a brief pointer to when a sibling tool should be used instead, which is already reflected in the usage dimension.

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

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

Schema description coverage is 100% and the input schema already describes identifier types and case-insensitivity. The description mostly restates the accepted identifier forms, adding no significant new parameter semantics beyond the target resource, so 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 names a specific action ('Resolve') and a concrete resource ('family-office records'), and it lists the accepted identifier forms (LEI, legal name, alias, register id). It is clear on its own, though it does not explicitly differentiate itself from siblings such as get_record or list_aliases.

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 use case is implied: call this when you have an identifier and need the family-office records and serving nodes. However, it never states when to prefer get_record, list_aliases, or list_nodes, and gives no exclusions or alternative conditions.

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