Nexus Catalyst

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds the key behavioral context that this returns complete preserved content rather than truncated summaries, which clarifies output expectations beyond the schema. No contradictions found.

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 is crisp and action-oriented, and the second paragraph adds useful pattern context without redundancy. The description is not bloated; it front-loads the core action and then provides the sibling contrast. A minor nit is the slight repetition of the parameter origin in both 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?

The tool has only one parameter, a clear purpose, and an output schema (per context signals) so return format is not the description's burden. The description explains the tool's role in the recall→detail pattern and its relationship to siblings, which is complete for an agent to call it correctly.

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

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

The single parameter memory_id is fully described in the schema ('The memory_id returned by recall_context or search_memories'), and the description reiterates the same source. With 100% schema coverage, the description adds no new semantic value beyond the schema, so the baseline of 3 is appropriate.

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

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

States a specific verb 'fetches' and a precise resource 'full stored content of one memory', and explicitly names the parameter (memory_id). It distinguishes itself from siblings recall_context and search_memories by contrasting their 150-token truncation with its complete content, making the tool's purpose 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?

Directly states the usage pattern: 'by the memory_id returned from a search' and identifies the siblings it complements ('recall_context and search_memories return summaries... this returns the complete...'). This gives the agent a clear when-to-use instruction and names alternatives, leaving nothing to inference.

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

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

Annotations already declare read-only, idempotent, and non-destructive behavior. The description adds meaningful behavior beyond this by disclosing that an out-of-set persona name returns a PERSONA_NOT_FOUND error rather than a substitute or invented definition, which directly addresses failure mode and hallucination risk.

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

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

The description is two short paragraphs with no filler. The primary purpose is front-loaded, and the second paragraph efficiently conveys the key parameter source and error behavior.

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 only one parameter, annotations covering safety, an output schema, and a description that explains both success content and error behavior, the tool is fully specified for correct invocation. No critical information is missing.

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

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

The schema only describes persona_name as 'Name of the persona to retrieve', which is minimal. The description adds crucial semantics by specifying that the correct value comes from recall_context's persona_hint, giving the agent actionable guidance beyond the schema.

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

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

The description states a specific verb and resource: it returns the full definition, communication style, and behavioral guidelines for one named persona. It clearly distinguishes this from the sibling memory and integration tools by scoping to the user's NC persona set, so an agent can immediately tell what this tool is for.

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 explicit context for obtaining the correct persona_name by referencing the value returned as persona_hint by recall_context. It does not explicitly name alternatives or say when not to use this tool, but the provenance guidance makes the correct usage clear.

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

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

Annotations already establish readOnlyHint=false and destructiveHint=true; the description adds behavioral context by emphasizing that 'every action here writes' and by naming the affected record types, including the less obvious 'memory↔issue cross-reference rows.' It does not detail side effects like overwrites or reversibility, but with destructiveHint already present, the added context is sufficient.

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 front-loaded with the core semantic ('CREATE OR MODIFY'), then a compact list of actions, then the workspace note. No filler; every sentence carries information an agent needs.

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 action selection and workspace disambiguation, but it lacks per-action parameter guidance (e.g., required fields for create_linear_issue vs create_linear_label). Given the open-world schema and ten actions, an agent may know which action to call but not how to populate the remaining arguments; output schema may compensate, but the description itself has this gap.

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

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

The schema only describes 'action' generically as 'The action to perform.' The description adds the full list of action names and, crucially, documents the workspace parameter that is not present in the schema (via additionalProperties). This goes beyond the schema's shallow 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?

Description states a specific verb-resource pair ('Linear actions that CREATE OR MODIFY records') and enumerates all included actions (issues, projects, labels, comments, cross-reference rows). It explicitly differentiates from sibling integration_query by saying 'Use integration_query for reads.'

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

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

The description gives an explicit exclusion: 'Every action here writes. Use integration_query for reads.' This tells the agent when to use this tool vs the read sibling. It also provides a conditional usage instruction: 'Pass workspace to select the Linear workspace when more than one is connected.'

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

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

The annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false; the description reinforces this safety profile with the explicit 'NEVER creates or modifies anything'. It adds value beyond annotations by explaining the workspace selection behavior and the breadth of read-only actions available.

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 front-loaded with its core purpose and safety guarantee, followed by the action list and workspace guidance. The action list is lengthy but necessary for a router-style tool; there is minor redundancy with the annotations but 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?

The description covers overall scope, safety, and workspace selection, and the output schema exists to explain return values. However, each of the 13 actions is only named, not explained; the agent may struggle to know the required arguments or semantics of less obvious actions like get_project_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?

The schema only describes the action parameter generically, but the description adds meaning by listing all valid action values and explaining the workspace parameter's purpose. This compensates for the schema's minimal parameter detail.

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

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

The description clearly identifies the tool as performing read-only Linear queries, enumerating the resources it can fetch (issues, projects, teams, labels, statuses, users, comments). It explicitly contrasts itself with integration_mutate, making its scope unambiguous.

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

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

The description explicitly states that this tool should not be used for creation or modification, directing the agent to integration_mutate instead. It also gives concrete guidance on passing workspace when multiple Linear workspaces are connected.

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?

Despite readOnlyHint/idempotentHint annotations, the description adds substantial behavioral context: first-call-only user_facts per conversation_id/program_tool, user_facts treated as data not instructions, summary truncation to 150 tokens, persona_hint indirection, and reappearance behavior after update_user_facts. This goes well beyond what annotations alone provide.

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 well organized with labeled sections and front-loaded purpose, but it repeats the return shape: the first paragraph already mentions truncated summaries, memory_ids, and persona_hint, and the final paragraph restates them. Otherwise, each section earns its place.

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

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

For a complex tool with 6 parameters and an output schema, the description covers relevance, retrieval behavior, full-query handling, user_facts lifecycle, truncation, and persona resolution. Nothing essential for correct invocation appears missing.

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

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

Schema coverage is 100% and parameter descriptions are already detailed. The prose adds minor nuance, such as query may stay a short topic label and use_full_query default behavior, but it mostly restates what the input schema already documents, so the 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?

Opens with a specific verb and resource: Semantic search over the user's NC memory store, and states the output shape: truncated summaries, memory_ids, and persona_hint. It is clearly not a tautology, but it does not explicitly distinguish itself from the similarly named sibling search_memories.

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

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

Gives concrete guidance on when recall is most relevant: requests referring to prior work, ongoing projects, established preferences, or anything the user treats as already known. It does not offer explicit when-not-to-use guidance or name an alternative tool for other cases, so it stops short of a 5.

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

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

Annotations already mark the tool as read-only, idempotent, and non-destructive. The description adds meaningful behavioral detail beyond that: the hybrid retrieval path (vector + KG entity-pivot + ACL), scoped matching behavior, truncated summaries, and the relationship between query and user_query_full. It does not contradict the annotations.

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

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

Three sentences, each earning its place: core purpose and scope, parameter guidance for fidelity, and return-format with a resolution path. The most important scoping information is front-loaded, with no redundant filler.

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

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

For a search tool with six parameters, an output schema, and safety annotations, the description covers what an agent needs to invoke it correctly: what it searches, how it differs from session recall, when to use the full query, what it returns, and how to get full content via get_memory_detail. Nothing essential is missing.

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

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

Schema coverage is 83%, so the schema already documents most parameters. The description adds real value by explaining the semantic distinction between query and user_query_full: user_query_full is the verbatim request used for higher-fidelity matching, while query is the fallback. This goes beyond the schema's individual field 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 opens with a specific verb and resource: 'Ad-hoc semantic search of the NC memory store over the hybrid recall path'. It also distinguishes itself from session-level recall by stating it is 'scoped to whatever is asked for' and reaches material the initial session recall missed, which separates it from siblings like recall_context.

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

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

The description gives clear usage context: use it for ad-hoc retrieval beyond session recall, and for higher-fidelity retrieval pass user_query_full verbatim. It also points to get_memory_detail as the follow-up for full content. However, it does not explicitly name alternatives or state when not to use 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?

Annotations carry the safety profile (readOnlyHint=false, destructiveHint=false, no contradiction). The description adds valuable behavioral context beyond the annotations: storage is cheap so more detail retrieves better, recall returns only what earlier sessions stored, and the caller composes summary/context from the conversation rather than from the user. This helps the agent reason about side effects and persistence without contradicting the structured data.

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?

Well-structured with clear section headers ('WHAT IS WORTH RECORDING', 'FIELDS') that make scanning easy. The description is long but every section earns its place — the field documentation adds genuine guidance rather than padding. Slightly more verbose than strictly necessary, but the structure mitigates this.

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 9-parameter memory-persistence tool, the description covers the core purpose, usage criteria, and field semantics thoroughly, and an output schema exists to handle return values. The optional metadata fields are not documented, but they are self-explanatory. The description gives the agent everything needed to record a session 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?

With 56% schema coverage, the description compensates meaningfully. It documents summary (50-75 tokens, one tight paragraph), user_query (verbatim, no truncation, matched against the user's own words), context (2000-8000 tokens, technical details untruncated), and conversation_id (must match recall_context). This goes beyond the schema by explaining the why behind each field. Undocumented params (persona, billable, artifact_url, client_project, company_client) are self-descriptive metadata fields, so the gap is acceptable.

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

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

States a specific verb-resource pair — 'Records the outcome of a session to the user's NC memory, so that later sessions can recall it.' This clearly distinguishes it from sibling readers like recall_context and search_memories, and the description explicitly contrasts it: 'Recall returns what earlier sessions stored and nothing else.' The agent can immediately tell what this tool is for and what it is not.

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 when-to-use criteria under 'WHAT IS WORTH RECORDING' — a session that produced something a later session would reconstruct (decision+reasoning, fix+why, constraint, state change), and explicitly states when NOT to use it: 'A session that only answered a self-contained question leaves nothing to recall.' This is direct usage guidance with a clear exclusion rule.

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?

Even though annotations already mark destructiveHint=true and idempotentHint=true, the description adds meaningful behavioral context: null deletes paths, the document is injected into future recall_contexts, writes over ~4KB are rejected, and corrections overwrite rather than accumulate. This explains the consequences of a write beyond what the annotations convey.

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 front-loaded with the operation and its key consequence, then uses clear headings to organize content policy. It is longer than average but every section earns its place for a tool with delicate usage rules; minor trimming of labels like 'instruction set v1.2' would tighten it slightly.

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

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

For a mutation tool with one parameter and an output schema, the description covers the operation, document content rules, merge semantics, size limits, failure behavior, and relationship to sibling tools. An agent has everything needed to invoke it correctly and avoid common misuse.

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

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

The single parameter has 100% schema description coverage with RFC 7386 semantics and a concrete example. The description restates 'set paths to values; null deletes a path' but does not add meaning beyond the schema; the baseline 3 applies because the schema already handles parameter documentation.

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: 'Updates the user's durable facts document with a JSON merge patch.' It immediately clarifies the exact mutation mechanism and distinguishes the document from session-specific storage by stating it is injected into every new conversation's recall_context.

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

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

It explicitly tells the agent what belongs in this document (durable truths) and what does not (session-specific, task-specific, time-boxed material), and names store_context as the alternative for excluded content. It also adds the rule 'Data, never rules,' which prevents misuse.

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