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

With no annotations, the description carries the burden of behavioral disclosure. It indicates a write operation ('append') and adds context ('follow-up', 'submitted root entity'), but does not mention permissions, idempotency, or what happens if the entity is not submitted.

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 efficiently conveys the purpose and key details. No extraneous words or repetition.

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

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

For a simple tool with two parameters and no output schema, the description covers the action and parameter roles. It assumes prior context (entity already submitted, thread exists), which is reasonable given the tool name. Minor gap: no mention of message size limits or handling.

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% with adequate parameter descriptions. The tool description adds minor value by framing the message as a 'follow-up conversation' and connecting entity_id to a 'root entity', but does not significantly enhance 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 clearly states the action ('Append a follow-up conversation_message'), the resource ('thread for a submitted root entity'), and references the key parameter 'entity_id'. It distinguishes from the sibling 'add_issue_message' by specifying it is for entities, not issues.

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 when a user wants to add a follow-up message to an entity's thread, but it does not explicitly state when to use this tool versus alternatives like 'add_issue_message'. No when-not or prerequisite guidance is provided.

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 provided, so description carries full burden. It discloses side effects ('If remote append fails after local/GitHub side effects') and error handling, though it does not explicitly state the write nature (implied by 'append').

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

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

Two sentences, no fluff. Every sentence conveys essential guidance including alternatives and error handling.

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?

No output schema, but description covers error handling and side effects. Given 8 parameters (1 required), it provides sufficient context for an agent to invoke correctly, though success behavior is not described.

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 baseline is 3. The description adds value by clarifying the optionality between entity_id and issue_number and explaining the purpose of guest_access_token beyond schema descriptions.

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 'Append a message to an issue thread' with a specific verb and resource. It distinguishes from sibling 'add_entity_message' by targeting issues explicitly.

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

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

Provides explicit guidance on when to use entity_id vs issue_number, when to pass guest_access_token, and how to handle remote_submission_error. Lacks explicit when-not-to-use or direct alternative tool names, but context is strong.

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

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

Without annotations, the description bears full responsibility but only hints at the registration process. It incorrectly implies only bidirectional sync while the schema includes push and pull. No mention of side effects, auth requirements, or post-registration behavior.

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

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

The description is a single sentence with no wasted words. However, for an 11-parameter tool, it is under-specified and could benefit from a brief list of required fields.

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 high complexity (11 params, no output schema, no annotations), the description is insufficient. It does not explain the peer_config concept, expected return, or follow-up actions.

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

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

Schema description coverage is only 27%. The description adds meaning for peer_url, entity_types, and shared_secret but omits 8 of 11 parameters, including required ones like peer_id, direction, and auth_method.

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 action 'Register' and the resource 'Neotoma peer', and mentions key aspects like peer_url, entity_types allowlist, and shared_secret. It distinguishes the tool from siblings such as remove_peer and sync_peer.

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 provides no guidance on when to use this tool versus alternatives like sync_peer or remove_peer. It does not specify prerequisites or scenarios.

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 must fully convey behavior. It only states the output (recommendations with confidence scores) but does not disclose whether the tool is read-only, requires special permissions, or has side effects. This is a significant gap.

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 sentences, front-loaded with the action, and contains no extraneous words. 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?

Given the lack of output schema, the description should ideally clarify the structure of recommendations. It states 'recommendations with confidence scores' but no further detail on format or nesting. Adequate but not rich.

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 does not add additional meaning beyond what the schema already provides for each parameter, though it does mention 'confidence scores' which relates to min_confidence.

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 verb 'Analyze' and the resource 'raw_fragments' to identify schema field candidates. It distinguishes from siblings like 'get_schema_recommendations' and 'register_schema' by focusing on analysis rather than retrieval or registration.

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 on when to use this tool versus alternatives (e.g., 'get_schema_recommendations'). The description does not specify prerequisites or conditions for use, leaving the agent to infer 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?

Without annotations, the description fully discloses read-only behavior, return structure (including order), and purpose. No contradictions or hidden behaviors.

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?

Concise yet thorough: main purpose first, then return details, then usage. No redundant sentences.

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?

No output schema, but description compensates with detailed return structure. Missing explanation of user_id param limits completeness slightly.

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 50% (user_id lacks description). The description adds context for entity_type but omits user_id entirely. This leaves the agent guessing about user_id's role.

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 reports undeclared fragments and contrasts with siblings like update_schema_incremental. The verb 'Report' and resource 'undeclared raw_fragments' are specific, and the purpose 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?

Explicitly says to use it for triage before schema work, and mentions optional entity_type scoping. It doesn't explicitly state when not to use, but the read-only nature is clear 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?

No annotations are provided, so the description carries the full burden; it exceeds it by stating read-only/no persistence side effects, instance-wide scope, no arguments, response shape, null semantics, and exact behavior for 'enforced' vs 'advisory' modes. It also warns that violating calls are rejected and nothing is persisted.

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 first sentence front-loads the core return value, followed by usage timing, response shape, edge-case semantics, and enforcement behavior. Despite its length, every sentence adds distinct value; there is no wasted or redundant wording.

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

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

With no output schema and no annotations, the description must explain return values and safety, and it does so fully: response shape, null-policy interpretation, entity_id handling for correct(), enforcement consequences, and read-only nature. This is sufficient for an agent to decide when and how to invoke it.

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 baseline is 4; the description reinforces this with 'Takes no arguments: the policy is instance-wide, identical for every caller,' which explains why the schema is empty and removes any temptation to supply caller-specific arguments.

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 a specific verb and resource: 'Return this instance's data policy' and enumerates exactly which aspects are covered (purpose, scopes, write requirements, max sensitivity class). It clearly distinguishes itself from siblings like store/correct/describe_entity_type by framing it as the session-start introspection call.

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 instructs when to call: 'at the start of a session against an unfamiliar or shared instance, before your first store' and gives a reason. It also defines what null policy means (unrestricted, not deny-all) and how to interpret enforcement modes, making the use decision 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?

The description discloses that the tool returns the user_id and notes its automatic use in authenticated actions. With no annotations, it adequately communicates the core behavior, though it could mention if the result is cached or requires prior authentication.

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

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

Two concise sentences with no wasted words. The description is front-loaded with the action and resource, making it efficient.

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 no output schema, the description explains the return value ('user_id') and its significance ('automatically used for all authenticated actions'). This is sufficient for a simple tool, though it could specify the data type or format.

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?

No parameters exist, so the schema coverage is 100%. The description adds no parameter information, which is acceptable since none are needed. Baseline of 4 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 clearly states the tool retrieves the authenticated user ID with a specific verb ('Get') and resource ('authenticated user ID'). It is unambiguous, but does not differentiate from sibling tool 'get_session_identity' which may serve a similar purpose.

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

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

No guidance is provided on when to use this tool versus alternatives like 'get_session_identity'. The description lacks context for appropriate usage scenarios or prerequisites.

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 indicate readOnlyHint=true, and the description reinforces this with 'snapshot' and 'read-back'. It adds specific context about token-scoped access without contradicting annotations. No additional behavioral traits disclosed, but sufficient given annotations.

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

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

Single sentence with clear structure, front-loading the core action and then specifying the optional parameter. No wasted words.

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 2-parameter tool with annotations, the description covers the purpose and key parameters. However, without an output schema, it lacks details on the return structure or error behavior, leaving minor gaps in completeness.

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 50%: guest_access_token has a description in the schema, entity_id has none. The description mentions both parameters but adds minimal semantics beyond what the schema provides (e.g., no format or constraint details). Adequate but not exceptional.

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?

Clearly states the tool returns a JSON entity snapshot for a submitted entity_id, with optional guest_access_token for token-scoped read-back. It distinguishes itself from sibling tools like get_issue_status or get_relationship_snapshot by focusing on entity submissions.

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 (for retrieving a submission snapshot) but does not provide explicit when-to-use vs alternatives, nor exclusion criteria. The guest_access_token is mentioned but not explained when it should be used.

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 that it uses the same aggregation as GET /stats and sorts results. It does not mention any destructive behavior, which is expected as it is a read operation. However, it could add more detail about output format or pagination, but for a simple count 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 efficiently written in two informative sentences plus a third sentence differentiating from a sibling. There is no filler, and it is appropriately front-loaded.

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

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

Given the tool's simplicity (one optional parameter, no output schema, common read operation), the description is complete enough. It explains the return type (canonical entity counts), aggregation source, sorting, and usage context. No additional information is necessary for correct usage.

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% with one parameter (user_id) already described as optional and inferred from authentication. The description adds no further parameter details beyond what the schema provides, so baseline score of 3 applies.

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

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

The description clearly states the tool returns canonical entity counts by entity_type, using the same dashboard stats aggregation behind GET /stats, and sorts results by count descending then entity_type ascending. It also distinguishes itself from list_entity_types by specifying that this returns row counts while that returns field width.

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

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

Explicitly says when to use: 'Use this when the user asks for counts by type, histograms, or sorted totals.' It also mentions when not to use it by contrasting with list_entity_types. However, it does not explicitly state when not to use or provide alternative tools beyond the one sibling.

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 declare readOnlyHint=true, which the description supports by stating 'Return'. Additionally describes sync skipping behavior and token scope for remote read-through, adding context beyond annotations.

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

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

Two concise sentences: first states purpose, second covers parameter usage. No superfluous words; information is front-loaded.

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

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

Given no output schema, the description adequately states that status and thread messages are returned. Could be more detailed about structure, but covers the essential return content.

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

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

Schema coverage is 100%, so the schema already documents all parameters. The description adds minor value by clarifying usage of guest_access_token and noting issue_number is an integer, but does not significantly extend schema info.

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 clearly states 'Return issue status and thread messages' with specific resource (issue) and verb (return). Distinguishes from siblings which are for other operations like creation, update, or deletion.

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

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

Provides guidance on how to identify the issue (entity_id or issue_number) and when to use guest_access_token. Lacks explicit when-not-to-use or comparisons with alternatives like get_entity_submission_status.

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 full burden. It adds context about the remote health check including '/health probe' and 'semver compat vs this server', but does not disclose potential error conditions, authentication needs, 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 a single, efficient sentence that front-loads the action and resource. It wastes no words, though slightly more structure could improve 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?

Given no output schema or annotations, the description lacks completeness. It does not explain the output structure, error handling, or prerequisites, leaving an agent with insufficient information for reliable 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 description coverage is 0%, so description must compensate. It mentions 'peer_id' as the identifier but adds no details on format, constraints, or how the parameter is used 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 clearly states 'Fetch peer_config by peer_id plus remote_health', specifying the action and resources. It distinguishes itself from sibling tools like 'list_peers' by focusing on a single peer's detailed status.

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 when you need peer config and health for a specific peer, but provides no explicit guidance on when to choose this tool over alternatives like 'list_peers' or 'sync_peer'.

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, description bears full burden. It implies a read operation but doesn't confirm safety, side effects, or response behavior. No mention of authorization, rate limits, or what happens if no recommendations exist.

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

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

Single sentence efficiently conveys action and sources. Front-loaded with verb and resource, no 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?

No output schema provided, but description does not describe what recommendations contain (e.g., field changes, confidence). Missing details on pagination or ordering. Incomplete for a 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 has 100% description coverage. Description adds 'from raw_fragments analysis, agent suggestions, or inference' which partially overlaps with source enum. Adds marginal value beyond 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 clearly states verb 'get', resource 'schema update recommendations', and scope 'for an entity type from raw_fragments, agent suggestions, or inference'. Distinguishes from sibling tools like analyze_schema_candidates by focusing on recommendations.

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 on when to use this tool vs alternatives like analyze_schema_candidates or other sibling tools. Lacks context about prerequisites or typical scenarios.

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 full burden. It states the tool does not write any rows, which is good. However, it lacks details on potential performance impact, authentication requirements, or any rate limits that might affect usage.

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 sentences long, front-loaded with the purpose, and includes critical usage guidance. Every word contributes value 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?

Given no output schema, the description adequately lists the key fields returned (trust tier, AAuth/clientInfo, anonymous-write policy, write eligibility) and clarifies safety. This is complete for a simple, zero-parameter introspection 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?

There are no parameters, so the schema coverage is trivially 100%. The description does not need to add parameter info. Per the guideline, 0 parameters yields a baseline of 4.

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 resolves the current session's attribution details including trust tier, AAuth/clientInfo fields, and write eligibility. It distinguishes itself from sibling tools like get_authenticated_user by focusing on session identity rather than just user info.

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 states it is safe to call as a preflight health check and does not write any rows, which guides when to use it. However, it does not explicitly mention scenarios to avoid or alternative tools for related queries.

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 bears the full burden. It states the output is a snapshot and that the webhook secret is omitted, which is useful. However, it does not disclose permissions, error conditions, or whether the operation is a read (implied by name but not explicit). Lacks details on side effects or rate limits.

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, front-loaded with the main action, and includes a clarifying parenthetical. Every word earns its place; no fluff.

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 tool's simplicity (one required param, no output schema, no annotations), the description is nearly complete. It tells what it returns and what is omitted. However, it could mention potential null return or error cases, but for a basic retrieval, this is sufficient.

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%, requiring the description to compensate. The description only says 'by subscription_id', adding little beyond the schema's property name. It does not explain the format, constraints, or how to obtain the ID. Baseline would be 3 if coverage were high, but here it's low and the description fails to fill the gap.

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 clearly states 'Return one subscription snapshot by subscription_id', which is a specific verb and resource. It distinguishes from siblings like list_subscriptions (which returns multiple) and subscribe/unsubscribe (which are mutations). The parenthetical note about omitting webhook secret adds precision.

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 when you need a single subscription snapshot, but does not explicitly state when to use this vs. alternatives (e.g., list_subscriptions for multiple, subscribe for creation). No when-not-to-use guidance is provided.

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 exist, so the description carries full burden. It discloses the check logic and auto_fix action, but does not explain what recompute entails (e.g., permissions, side effects) or return details like health status format.

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

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

Two sentences with no redundancy. The primary purpose and key parameter are front-loaded. 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 no output schema and one optional parameter, the description sufficiently explains purpose and auto_fix. However, it could explicitly state the return type (e.g., a JSON object with 'stale_count'), but overall it's adequate.

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 description adds meaning by explaining auto_fix default and effect. The description goes beyond schema by clarifying the conditional recompute behavior.

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

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

The description clearly states the tool checks for stale entity snapshots, defines the condition (observation_count=0 with existing observations), and specifies outputs (health status and count). It uses specific verb and resource, distinguishing it from unrelated 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 implies usage for monitoring snapshot health, but does not explicitly state when to use it versus other tools or provide exclusions. No guidance on alternatives like other health checks 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?

No annotations exist, so the description must carry the full burden. It discloses output structure (best_match, identity_score, etc.) but does not mention side effects, idempotency, or authentication requirements. For a resolution tool, this is adequate but not comprehensive.

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

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

Two sentences, front-loaded with purpose and output structure. No superfluous words. Every sentence earns its place.

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

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

Given the tool's complexity (nested signals, multiple parameters, no output schema), the description adequately covers return values and usage scenario. It does not explain the resolution algorithm fully, but that level of detail is unnecessary for agent selection.

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%, but the description adds value by explaining canonical weights for well-known keys and weight 0.4 for open-ended keys, which the schema lacks. This aids the agent in understanding signal importance.

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's action: resolving an entity from a multi-signal bundle (name, email, company, domain, phone, open-ended strings). It specifies output fields (best_match, identity_score, resolution_band, etc.), distinguishing it from sibling tools like retrieve_entities that use exact IDs.

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 is provided: 'Use when you have partial or combined identity information and want a single-call resolution with confidence scoring.' It does not explicitly state when not to use or list alternatives, but the context of sibling tools implies alternatives for exact ID lookups.

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?

Description adds 'recent' implying ordering but does not clarify ordering criteria or pagination behavior. Annotations already declare readOnlyHint=true, so minimal added value.

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?

Single sentence, no fluff, but omits important details about parameters and behavior. Conciseness should not come at cost of completeness.

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?

No output schema, so description should indicate return structure. Does not mention pagination, ordering, or what 'recent entities' includes. Incomplete for a list tool with pagination parameters.

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

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

Only 'entity_type' is implicitly explained as the filter. 'limit' and 'offset' are not described despite being crucial for pagination. Schema description coverage is 0%, so description should compensate but does not.

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

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

Description clearly states verb 'list', resource 'entities', filter by 'entity_type', and scope 'for the authenticated user'. It distinguishes from sibling 'list_entity_types' but not from similar list tools like 'retrieve_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?

No guidance on when to use this tool versus alternatives like 'retrieve_entities' or 'submit_entity'. No when-not-to-use or prerequisites mentioned.

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 provided, but the description discloses key behaviors: two modes of operation, hybrid search mechanism, meaning of field_count. Lacks details on pagination or rate limits but sufficient for core functionality.

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?

Single well-structured paragraph, front-loaded with purpose, then behavior details. Every sentence adds value 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?

Given the complexity (3 parameters, two modes, hybrid search), the description covers the key behaviors and return structure hints. Could mention user_id role and edge cases, but sufficient for most use cases.

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?

With 0% schema description coverage, the description explains keyword and summary parameters thoroughly. user_id is not explained, leaving a gap, but the other two parameters are well-covered.

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 available entity types, with distinct behaviors for with and without keyword. It distinguishes itself from sibling tools like get_entity_type_counts and retrieve_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?

Explicitly says 'Use before storing structured data to determine the correct entity_type', giving clear when-to-use guidance. Does not mention when not to use or alternatives, but sibling tools are distinct.

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 provided. Description states it lists runs for the authenticated user with optional source_id filter, but lacks details on authentication requirements, side effects, rate limits, or handling of empty results. The description is too brief to compensate for missing annotations.

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

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

A single concise sentence, but it lacks detail. It is not wasteful, but the brevity sacrifices informativeness.

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?

Without output schema or annotation support, the description is critically incomplete. It omits pagination details (limit/offset), the meaning of user_id, and what an interpretation run entails, leaving the agent with insufficient context.

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 has 4 parameters (user_id, source_id, limit, offset) with 0% coverage in schema descriptions. The description only mentions source_id as an optional filter, adding no meaning for user_id, limit, or offset.

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 action (list) and resource (interpretation runs) with authentication scope and optional filtering. However, it does not distinguish from any close sibling tools, as there is no other list-interpretations tool among siblings.

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 explicit guidance on when to use this vs. alternatives. It mentions optional filtering but does not specify when not to use or prerequisites. No contrast with create_interpretation or other list tools.

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 bears full responsibility. It fails to disclose pagination, default parameter behavior, or error responses, leaving agent uninformed.

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 short sentence, but it omits critical details and does not earn its place by being informative. It is under-specified rather than concise.

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 5 parameters, no output schema, and no annotations, the description is woefully incomplete. An agent cannot determine proper usage, pagination, or what constitutes an observation.

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 low (40%), but description adds no parameter information. The phrase 'for a given entity' suggests entity_id is needed, but the schema marks it not required, creating confusion.

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 'List all observations for a given entity', which identifies the resource and action. However, it does not differentiate from sibling list tools (e.g., list_interpretations, list_peers) and is ambiguous about whether entity_id is required.

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 on when to use this tool vs. alternatives. Among many list tools in the sibling list, the description lacks context for 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?

No annotations are provided, so the description carries full burden. It discloses that secrets are redacted, which is a behavioral trait. However, it does not mention idempotency, authentication requirements, or output format. For a simple list operation, this is acceptable but not thorough.

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 concise sentence that effectively communicates the purpose and key behavioral note. No extraneous words; every part 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 simplicity of the tool (no parameters, no output schema), the description covers the essential aspects: purpose and secrets redaction. It could be slightly more explicit about returning all rows, but overall it is sufficient.

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 has no parameters, so schema description coverage is 100%. The description does not add parameter information, but none is needed. Baseline score of 3 applies.

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

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

The description clearly states the tool lists peer_config rows for the current user, with a note about secrets redaction. It uses a specific verb and resource, and the scope is explicit. It distinguishes from sibling tools like add_peer or remove_peer.

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 explicit guidance is given on when to use this tool versus alternatives like get_peer_status or sync_peer. The name and description imply it's for listing, but no when-to-use or when-not-to-use information is provided.

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 provided, but description fully covers behavioral traits: read-only, fuzzy post-hoc detector, never auto-merges, threshold override. No contradiction.

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, each adding essential information. No wasted words. Purpose, usage, and behavior are front-loaded.

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

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

No output schema, but description covers key aspects: input, behavior, and next steps. Minor missing detail on return format (e.g., pairs with similarity scores), but sufficient for agent understanding.

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 has 100% coverage for 4 parameters. Description adds meaning by explaining that per-schema thresholds come from schema fields and callers may override threshold per call, going beyond raw schema descriptions.

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 clearly states it lists candidate duplicate entity pairs for a given entity_type. Distinguishes itself from sibling merge_entities by explaining it is the detection step before merging.

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 it is read-only and never auto-merges, advises confirming with user before calling merge_entities. Explains threshold behavior and override capability.

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

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

The annotation 'readOnlyHint: true' already indicates a safe read operation. The description adds context about the tables scanned, ordering by 'activity_at', and authentication requirement, which enriches the behavioral understanding beyond the annotation.

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, well-structured sentence that efficiently conveys the tool's purpose and key behavioral details (tables, ordering, authentication). No redundant information 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?

No output schema is provided, and the description does not specify the structure of returned items (e.g., whether they contain full records or just IDs). Given the tool aggregates across multiple tables, more detail about the output format would improve completeness.

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 both parameters (limit, offset) have clear descriptions in the input schema. The description does not add any parameter-specific meaning; it only mentions ordering. With high schema coverage, a score 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 clearly states the verb 'List', the resource 'recently changed records across core Neotoma tables', and specifies the scope 'for the authenticated user'. It distinguishes itself from sibling list tools like list_interpretations or list_observations by aggregating across multiple tables.

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 this tool is for retrieving a recent activity feed, but it does not explicitly state when to use it versus the many sibling list tools (e.g., list_entity_submissions, list_relationships). No 'when not to use' or alternatives are provided, leaving the agent to infer 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?

No annotations provided; description only notes webhook secrets omitted. Lacks disclosure of side effects, auth requirements, rate limits, or response 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?

Single sentence with clear verb and caveat. Front-loaded and no wasted words.

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?

No output schema or annotations. Description is minimal but adequate for a simple list; lacks explanation of return format, pagination, or error handling.

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?

No parameters (baseline 4). Description adds meaning by specifying scope and omission, which is helpful beyond 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?

Clearly states verb 'List', resource 'subscriptions', scope 'current user's active', and caveat about webhook secrets. Distinguishes from siblings like 'subscribe' and 'unsubscribe'.

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 on when to use this tool versus alternatives (e.g., subscribe, unsubscribe) or context for the list.

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

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

The annotation already indicates readOnlyHint=true. The description adds that events are chronological and derived from date fields, providing some context beyond the annotation, but does not disclose pagination behavior, ordering defaults, or other traits present in the schema.

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

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

Two sentences with no wasted words. The first sentence immediately states the action and scoping filters. Information is front-loaded and essential.

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 7 parameters, no output schema, and no parameter description coverage, the description is too brief. It does not explain what constitutes a timeline event, how sources relate to parameters, or the meaning of ordering/pagination. More context is needed for a complete understanding.

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% (no parameter descriptions). The description mentions filter types (type, date range, source) but does not map them to specific parameters (event_type, start_date/end_date, user_id) nor explain limit, offset, or order_by. It fails to compensate adequately for the lack of schema descriptions.

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 it queries timeline events with filters, specifying filter dimensions (type, date range, source). This provides a specific verb and resource, distinguishing it from sibling tools that list other entities like observations or relationships, though explicit differentiation is missing.

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 for querying timeline events with filters but provides no guidance on when to use this tool versus alternatives (e.g., list_observations or list_relationships) or 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?

With no annotations provided, the description carries full burden and excels: it explains action-specific outputs, persisted state toggling, exceptions for default bundles, side effects of disabling (stops auto-creating types while preserving data), and the return type (structured JSON). No contradictions with annotations.

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

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

The description is concise and well-structured: three sentences with the main verb+resource up front, followed by action details and constraints. Every sentence adds 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?

Despite lacking an output schema, the description covers all action types, required parameters, exceptions, side effects, and return format. The tool's complexity is fully addressed in a compact space.

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 parameters already have descriptions, but the tool description adds behavioral meaning beyond the schema (e.g., what happens when disabling a bundle, what list returns). This goes beyond the baseline of 3 for high schema coverage.

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's purpose: 'Inspect and manage Neotoma bundles' and enumerates specific actions (list, info, install, enable, disable) with distinct outcomes. This differentiates it from sibling tools focused on entities, relationships, and other domains.

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 provides usage context for each action (e.g., 'action=info (with bundle) returns full manifest detail') and notes constraints like default-install bundles cannot be disabled. It does not explicitly name alternative tools, but the sibling list shows no overlapping bundle tools, so the guidance 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?

No annotations provided, so description must disclose behavioral traits. It mentions rewriting observations and marking source, but does not clarify if source is deleted, whether observations are moved or copied, or any destructive side effects. Missing critical details for a mutation 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?

Two concise sentences, no fluff, front-loaded with the primary action and key effect.

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?

No output schema, so description should explain return value. Does not mention result of merge (e.g., success/failure, status of source entity). With 4 parameters and no schema descriptions, the description is too sparse for an agent to fully understand the tool's behavior.

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 has 0% parameter descriptions. The description does not explain any parameter (from_entity_id, to_entity_id, merge_reason, user_id) beyond their names. Names are somewhat self-explanatory but incomplete for an agent to invoke correctly without format constraints.

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 action (merge), resource (entities), and the effect: rewrites observations and marks source as merged. It distinguishes from sibling tools like split_entity.

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?

Implied usage for deduplication, but no explicit guidance on when to use vs alternatives (e.g., delete_entity, split_entity). No prerequisites or exclusions mentioned.

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 provided, so description carries full burden. It explains what the tool computes and how entities are resolved, but does not disclose whether it is read-only/destructive, nor any side effects or permissions.

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 concise; every sentence adds value. The ticket number 'FU-2026-05-002' is slightly extraneous but does not detract significantly. Front-loaded with main 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?

Given no output schema, the description explains what the returned status_line and widget_uri are for. Missing explicit return structure and error handling, but adequate for a straightforward compute 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?

Adds meaning beyond schema: specifies turn_key format, explains conversation_id disambiguation, and notes server entity resolution. Only user_id lacks description in both schema and text, but it's optional.

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 explicitly states the tool computes the per-turn Neotoma status line and optional widget URI, with clear verb-resource pairing. The task is unique among siblings, no 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?

Clearly says when to call 'at the end of every turn after the closing assistant store completes.' Does not explicitly state when not to call, but 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 bears full responsibility for disclosure. It thoroughly explains the tool's behavior: it fetches npm registry data, includes optional release notes and capability delta, indicates best-effort nature, and clarifies conditions under which fields appear (e.g., capability_delta_note only on degradation). No contradictions.

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 lengthy but each sentence contributes necessary detail. It fronts the core purpose and then systematically lists return fields and conditions. Could be slightly more concise, but the complexity of the tool justifies the length.

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 absence of an output schema, the description fully documents all return fields and their conditional presence. It covers every aspect of the tool's behavior, leaving no ambiguity for an AI agent to invoke or interpret 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 100%, so baseline is 3. The description adds value by explaining the effect of each boolean flag on the return object (e.g., include_release_notes adds release_url and excerpts; include_capability_delta adds new_tools, removed_tools, etc.). This goes beyond the schema's descriptions.

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 begins with 'Check if a newer npm version is available', a specific verb and resource. It then details the return values, clearly distinguishing this tool's purpose from any sibling tools, none of which deal with npm version checking.

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 states when to use the tool ('Call at session start to encourage user to upgrade'), providing clear context. It does not mention when not to use it or alternatives, but given the unique purpose among siblings, this is not a significant gap.

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 provided, so description handles transparency. Mentions no storage and output of text and images, but lacks detail on error handling, output format, or behavior with large files.

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

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

Two sentences, front-loaded with purpose, no wasted words. Highly concise and easy to process.

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?

No output schema, so description should clarify return format. Mentions 'text and first-page PDF images' but not structure or data type. Good for intended use but could be more 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 covers 100% of parameters with descriptions. The tool description adds context about preferred local file path but doesn't significantly enhance per-parameter semantics beyond 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?

Clearly states it parses files into text and first-page PDF images, and explicitly says it does not store anything, distinguishing it from the 'store' sibling tool.

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 tells when to use: 'Use before store when you need to extract entities from a file.' Provides clear guidance on context and intended workflow.

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

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

The description discloses key behavioral traits: each call mints a fresh token, tokens are hash-only at rest, html_body is injected verbatim without wrapper elements, and idempotency key behavior for inline creation. These details go beyond the schema and annotations (which are absent), fully informing the agent of side effects and constraints.

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, dense paragraph that front-loads the purpose and then efficiently covers details. Every sentence adds value, with no repetition or fluff. It is well-structured for an AI agent to parse quickly.

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?

The description covers the major aspects: usage modes, parameter behavior, token generation, and return value. It lacks error handling specifics and does not mention authentication requirements beyond 'user_id inferred from authentication.' Given the complexity (7 parameters, multiple modes), it is fairly complete but could include a brief note on failure cases.

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?

Although the input schema already has 100% description coverage, the description adds significant context: it explains the two usage modes (entity_id vs. inline fields), the verbatim injection of html_body, the purpose of idempotency_key, and the optional nature of user_id. This adds meaning beyond the schema alone.

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's purpose: turning a rendered_page into a ready-to-share guest URL. It outlines two distinct usage modes (pass an existing entity_id or create one inline) and specifies the return value (absolute URL with token and TTL). No sibling tool offers similar functionality, so it effectively distinguishes itself.

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 provides clear context on when to use the tool (to publish a rendered page) and the two modes. It does not explicitly exclude scenarios or mention alternatives, but given the sibling list lacks a direct alternative, a score of 4 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?

With no annotations provided, the description fully carries the behavioral burden. It explicitly discloses read-only behavior ('never creates a company entity'), the no-match return shape ('company: null and an empty contacts list'), the owner_user_id restriction ('must equal the authenticated user's id today'), and the resolution algorithm. This is exemplary transparency.

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 dense paragraph, but every clause earns its place: purpose, resolution order, read-only guarantee, no-match behavior, and owner scoping. It is front-loaded with the purpose and uses a clear colon to separate the core question from details. No redundant wording.

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?

The description covers resolution, read-only behavior, no-match scenarios, and owner override thoroughly. Since there is no output schema, it briefly mentions response elements (company:null, empty contacts, total_contacts in schema) but does not fully enumerate the response fields. Still, for a query tool of this complexity, it is 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?

Schema coverage is 100% for all three parameters, and the schema already explains limit, company_name matching, and owner_user_id semantics. The description adds context about resolution order and the live edge, but does not significantly enrich parameter-level meaning beyond what the schema provides. Baseline 3 is appropriate.

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

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

The description opens with the exact question it answers ('who do we have connected at company X') and clearly states it returns every contact linked to the resolved company via a live works_at edge. This specifies the verb (query/return), resource (contacts at a company), and scope (canonical company entity), and differentiates it from sibling tools like list_relationships by focusing on company resolution.

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 clear context: use when you need contacts linked to a company, with optional owner scoping. It explains the resolution order (exact-normalized then fuzzy) and the read-only nature, but does not explicitly name alternative tools or state when not to use this tool. This meets 'clear context, no exclusions'.

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

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

No annotations are provided, so the description bears full responsibility for disclosing behavior. It states 'Deactivate a peer' but does not clarify whether the action is reversible, what happens to associated data, or any authentication requirements. With zero annotations, this is insufficient.

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 very short (one sentence) and to the point. However, brevity comes at the cost of missing important details. It is not verbose, but could be improved slightly without losing conciseness.

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 simplicity of the tool (1 param, no output schema), the description is minimally acceptable but lacks behavioral context. It does not explain return values, side effects, or any error conditions. For a deactivation operation, more completeness is expected.

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 has one parameter 'peer_id' with 0% description coverage. The description merely repeats the parameter name ('by peer_id') without adding any semantic detail about format, constraints, or examples. The schema provides only a type string, leaving the agent with minimal understanding.

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 action ('Deactivate a peer') and the required input ('by peer_id'). It is specific enough to understand the tool's purpose, though it does not explicitly differentiate from sibling tools like 'sync_peer' or 'add_peer'.

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 on when to use this tool versus alternatives (e.g., 'add_peer' or 'sync_peer'). The description does not specify prerequisites, context, or 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?

No annotations provided. The description gives no behavioral information such as side effects, permissions, or success/failure conditions. 'Stub' implies the tool may not be functional, which is a critical behavioral trait left unspecified.

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 very short but not effectively concise—it omits essential information. 'Stub' indicates a placeholder, and the instruction to use an alternative tool suggests this description is not final.

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 tool has 4 parameters, no output schema, and no annotations, the description is grossly incomplete. It fails to explain what the tool does, when to use it, or what the parameters mean.

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 50% (only sender_peer_url and guest_access_token have descriptions). The description adds no meaning to parameters; it does not explain entity_id, strategy enum values, or how they interact.

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 'Stub; use correct on the entity for manual resolution today.' does not state what the tool does. 'Stub' implies it's incomplete or non-functional, and the reference to 'correct' confuses the purpose. No specific verb or resource is described.

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 on when to use this tool vs alternatives. The mention of 'use correct on the entity' suggests an alternative but provides no context or conditions for choosing this tool.

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 provided, so description carries full burden. It discloses strict-mode combination rules, alias handling, cursor and offset limitations, snapshot_filters behavior including `contains` vs `contains_word` semantics, case-insensitivity, and performance implications of include_snapshots. This significantly exceeds standard behavioral disclosure.

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

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

The description is long but densely informative with no filler. It is front-loaded with the primary use-case and then systematically covers constraints, filtering, and pagination. Every sentence provides actionable guidance for a high-complexity tool (21 params).

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 21 parameters, nested snapshot_filters object, and no output schema/annotations, the description covers use cases, constraints, filter semantics, pagination strategy, and performance advice. It mentions response elements (next_cursor, snapshot payloads) and error behavior. It is unusually complete for such a complex 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 covers all 21 parameters (100%), but the description adds substantial meaning: explains why limit is capped at 500 with snapshots, clarifies cursor vs offset trade-offs, snapshots filter operators with examples, lexicographic sort behavior, and the compatibility aliases. This is well beyond the schema's property descriptions.

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 explicitly states 'Use this when you need filtered entity lists' and 'lexical/semantic retrieval via search', clearly specifying a list/query operation on entities. It distinguishes from siblings like retrieve_entity_snapshot (single entity) by focusing on filtered lists and search.

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

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

Opens with 'Use this when you need filtered entity lists' and provides explicit constraints: search cannot combine with non-default sorting or published filters; include_snapshots=false for lightweight responses; cursor vs offset for deep pagination. Gives guidance on when to use snapshot_filters and compatibility aliases, plus conditions when cursor is unsupported.

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 discloses key behaviors: fallback to semantic search, short-circuit for entity_id, optional observations, and hints for missing ids. It does not cover authentication or rate limits but covers the main behavioral traits.

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 extremely concise, consisting of two sentences that front-load the purpose and then add critical behavioral details. Every sentence contributes value with no 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?

Given the moderate complexity (6 params, no output schema), the description covers the search algorithm, optional observations, and sibling tool hint. It lacks return value specifics but is largely complete for a 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 the baseline is 3. The description adds minimal parameter-specific context beyond the schema (e.g., normalization of identifier). It does not significantly enhance parameter understanding.

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 verb (retrieve), resource (entity), and the method (by identifier). It distinguishes from sibling tools like retrieve_entity_snapshot by noting the short-circuit behavior for literal entity_id and the hint to that tool.

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 but not explicitly stated. The description explains the fallback and short-circuit behavior but does not provide direct guidance on when to use this tool versus alternatives like retrieve_entities or retrieve_entity_snapshot.

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 fails to disclose behavioral traits such as read-only nature, authentication needs, or what 'provenance chain' implies; merely states the action.

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 concise but overly brief; it gets the point across but could benefit from additional detail without being verbose.

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 lack of output schema and annotations, the description is incomplete; it does not explain what the provenance chain contains or the return format, leaving the agent underinformed.

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

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

Schema description coverage is 0% and the description does not explain the two parameters (entity_id, field) beyond their names, leaving ambiguity about valid values and usage.

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 verb 'retrieve' and the specific resource 'provenance chain for a specific field in an entity snapshot', distinguishing it from siblings like retrieve_entity_snapshot.

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 on when to use this tool versus alternatives, nor any mention of exclusions or prerequisites.

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 must disclose behavioral traits. It fails to mention that the tool likely requires the file to already exist, whether it modifies anything, or if it returns a URL string. The term 'signed' implies authentication needs but is not explained.

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?

Single sentence conveying the core function with no unnecessary words. Highly efficient and front-loaded.

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

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

Given no output schema and no annotations, the description is too brief. It omits key details like return type, error scenarios, prerequisites (file existence), and any side effects. The agent cannot reliably use this tool without additional assumptions.

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?

Input schema has 0% description coverage. The description does not explain the parameters' meanings beyond their names. For expires_in, units and default are missing; file_path format is not clarified. The description adds little semantic value.

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 action (Retrieve) and resource (a signed URL for accessing a file), which distinguishes it from siblings like parse_file (reads content) or store (uploads). However, it does not explicitly clarify whether the URL is temporary or scoped to the current user.

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 on when to use this tool versus alternatives, nor any prerequisites or limitations. The description only states the function without contextual cues about scenarios (e.g., file must exist, requires authentication).

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. The description claims 'complete' but the schema includes limit/offset for pagination, contradicting completeness. It also omits important traits like that include_observations is entity-only and that results may be truncated. Not transparent about pagination or performance.

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 clear sentence, efficient and front-loaded. However, it could be structured better (e.g., bullet points for components) to improve readability, but it's not verbose.

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?

The tool has 8 parameters and no output schema, yet the description is very brief. It does not explain the output structure, pagination details (limit/offset), or the distinction between entity and source nodes. For a complex graph retrieval, more detail is needed to be 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 coverage is 100%, so baseline is 3. The description adds no additional meaning beyond the schema; it only lists components covered by parameters like include_relationships, include_sources, etc. No extra context on parameter values or behavior.

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

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

The description clearly states the action ('retrieve complete graph neighborhood') and the resource ('around a node'), listing the included components (entities, relationships, sources, events). This distinguishes it from siblings like retrieve_entities or list_relationships that retrieve only specific types.

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 when a complete neighborhood is needed but does not provide explicit guidance on when to use this tool versus alternatives like list_relationships or retrieve_related_entities. No when-not-to-use or alternative tools are mentioned.

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 must fully convey behavior. It states it retrieves entities, implying read-only, but does not mention performance implications of large max_hops, error handling, or response structure. The lack of behavioral details leaves agents uncertain.

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

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

Two sentences, front-loaded with purpose and key capability. Every word is informative and necessary.

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 5 parameters and no output schema, the description is too brief. It omits what the response contains (e.g., entity snapshots, relationship info) and doesn't clarify the role of 'include_entities'. For such complexity, more detail is needed.

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 parameters well. The description adds only high-level context ('n-hop traversal') but no extra parameter-level meaning. Baseline 3 is appropriate.

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

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

The description clearly states it retrieves entities connected via relationships, and mentions n-hop traversal. However, it does not differentiate from similar sibling tools like 'retrieve_graph_neighborhood', which likely serves a similar purpose.

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

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

The usage is implied: use when you need connected entities with support for multiple hops. No explicit guidance on when not to use it (e.g., when only direct relationships are needed, or when to prefer 'list_relationships' or 'retrieve_entity_snapshot').

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 fully discloses behavior: observations are never modified, only FK rebound; idempotency and error conditions (ERR_IDEMPOTENCY_MISMATCH); relationships are not affected. This is comprehensive for a mutation 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 concise (3 sentences) and front-loaded with the core purpose. It efficiently covers key behavioral aspects without unnecessary detail. Slightly dense but well-structured.

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 tool's complexity (6 params, nested objects, no output schema), the description provides a solid overview of purpose, behavior, and parameter usage. However, it could briefly mention the expected response format or success indicators.

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 covers 50% of parameters with descriptions, but the description adds significant value by explaining the predicate forms and their use cases (e.g., 'move every observation from this session forward'). It also clarifies idempotency_key semantics beyond the schema.

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

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

The description clearly states the tool is the inverse of merge_entities, specifically repoints observations to repair over-merges. It provides a concrete use case (pre-v1.2 heuristic name_key:title collapse) and distinguishes it from its sibling, merge_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?

Explicitly states when to use (repair over-merges) and when not to (typed relationships remain bound, use create_relationship instead). Also notes idempotency key reuse behavior, giving clear guidance on proper invocation.

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 must disclose all behavioral traits. It mentions creating a row and optional thread/token, but does not discuss side effects, idempotency, authorization needs, or what happens to existing submissions.

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, well-structured sentence that front-loads the purpose, then details optional outputs, then provides an alternative—all in 20 words.

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?

No output schema exists, so the description should hint at return values, but it does not. It covers the core function but omits behavioral context and output characteristics.

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 baseline is 3. The description adds context that fields is the payload and initial_message relates to conversation, but does not significantly enhance understanding beyond the schema descriptions.

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 it is a generic submission for entity types with an active submission_config, creates the primary row plus optional conversation thread and guest_access_token, and explicitly distinguishes from submit_issue for GitHub-backed issues.

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 names the alternative submit_issue for GitHub-backed issues, providing clear differentiation. However, it does not elaborate on prerequisites or when not to use this tool beyond that.

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 of behavioral disclosure. It is exceptionally transparent: it explains the authentication model (no Bearer token, AAuth signature, or guest token needed), that the token is an OUTPUT rather than a precondition, that anonymity covers only the submission, and the deprecated visibility alias behavior with exact response text. This gives the agent essential context about side effects and security aspects.

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 long but every sentence carries relevant information: purpose, token return, auth model, follow-up usage, required parameters, and deprecation warning. It is front-loaded with the main action. It could be better structured with bullet points for readability, but it is not verbose or wasteful.

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 12 parameters, no output schema, and no annotations, the description compensates well by explaining the return token, auth preconditions, required params, and deprecation behavior. It does not elaborate on all potential side effects (e.g., GitHub mirror behavior, error cases), but covers the most critical contextual information an agent needs to invoke the tool correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value beyond the schema by reinforcing the conditional requirement for reporter_git_sha/reporter_app_version (already in schema) and, more importantly, by documenting the deprecated 'advisory' enum value for visibility, which is not present in the schema. This extra semantic detail about an accepted value improves parameter understanding.

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 action ('Submit an issue') and target ('configured operator Neotoma instance'), with a specific verb and resource. It distinguishes this from sibling tools by naming the follow-up token-scoped read-back tools (get_issue_status / add_issue_message), making it clear this is the initial submission action.

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 provides explicit guidance: it states when this tool is appropriate (submitting without prior identity), what must be provided (at least one of reporter_git_sha or reporter_app_version), and how to proceed after acceptance (use returned token for get_issue_status/add_issue_message). It also notes the deprecated visibility alias, giving clear exclusions. However, it does not explicitly mention alternative tools for cases where a guest token already exists.

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 provided, so description carries full burden. It discloses delivery methods, filter requirements, and sync_peer_id functionality. Missing details on authentication, rate limits, error conditions, or what happens on failures.

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

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

Two sentences, front-loaded with purpose. Every sentence adds value without redundancy. Efficient and well-structured.

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?

No output schema, so description should hint at return value (e.g., subscription ID). It does not. Lacks authentication info but covers filters and delivery methods adequately. Moderate complexity; missing return info reduces completeness.

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 has 8 parameters with only 13% description coverage (only sync_peer_id described). The tool description adds meaning: explains filter requirement and loop prevention for sync_peer_id, but does not elaborate on webhook_url, webhook_secret, max_failures, or delivery_method semantics beyond listing.

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 action 'Create' and the resource 'substrate event subscription' with specific delivery methods (webhook with HMAC, SSE). It distinguishes from siblings like 'unsubscribe' and 'list_subscriptions' by detailing the creation process.

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

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

Provides explicit prerequisites: at least one filter among entity_types, entity_ids, or event_types. Also explains the use of sync_peer_id for loop prevention. However, it does not mention when not to use this tool or compare with alternatives like 'get_subscription_status'.

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. It reveals that other entity types may result in a no-op, which is helpful. However, it does not disclose side effects (e.g., overwriting, destructive actions) or permissions needed, leaving moderate gaps.

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, efficient sentence that packs key information: purpose, scope (issue to GitHub), and caveat (no-op for others). It is front-loaded and concise, with no wasted words.

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 simple input (one optional param) and no output schema, the description is fairly complete. It explains the primary use case and limitations, but leaves open questions about what 'sync' entails (direction, idempotence, success/failure behavior) and what 'external mirrors' refers to.

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 description covers the default behavior ('Defaults to issue when omitted'), and the tool description adds meaning by explaining that 'issue' triggers GitHub sync while other types are no-ops. This goes beyond the schema, providing valuable context for parameter values.

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 syncs external mirrors for submissions and gives a specific example (issue to GitHub sync). It uses a specific verb and resource, but does not explicitly distinguish itself from the sibling tool 'sync_issues', leaving slight 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 implies usage for syncing issues to GitHub and notes that other types may no-op until providers are added, providing some context. However, it lacks explicit when-to-use or when-not-to-use guidance and does not mention alternatives like 'sync_issues'.

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 full burden. It mentions 'POST' implying mutation, but does not disclose whether the operation is destructive, idempotent, or what side effects occur. The behavior beyond sending a request is opaque.

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, efficient and front-loaded with 'Bounded outbound peer sync'. However, it packs technical details (POST path, env vars) without punctuation or structure, making it somewhat cryptic.

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?