Custodio Legal

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

Annotations already state readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context beyond annotations: items are returned ordered urgent-to-low-priority, only open items are listed, and the operation has no decision-making 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?

Two tight sentences with no filler. The action, input, scope, ordering, and use case are all front-loaded, and every clause adds information.

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

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

For a simple read-only, single-parameter tool with no output schema and strong annotations, the description is complete. It specifies what is returned, the order, the input, and the intended purpose. Nothing an agent needs to decide whether or how to call it 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 has one required param with 0% description coverage, so the description must carry meaning. It does: 'identified by matter_id' and 'that Matter' make clear the parameter identifies the Matter whose attention items should be listed. For a single self-explanatory UUID parameter, this is sufficient, though it does not explain how to obtain the ID.

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

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

The description names a specific verb ('List') and resource ('open attention items of the Matter identified by matter_id'), and adds ordering from urgent to low priority. It also clarifies what these items represent ('what in that Matter still needs a human decision'), which clearly differentiates it from the sibling get_* tools that retrieve evidence, changes, state, or timeline.

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

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

The description explicitly says when to use the tool: to find items in a Matter that still need a human decision. It does not explicitly name alternatives or say when not to use it, but the stated use case is clear and the phrase 'it reads and decides nothing' implies it is for assessment rather than action.

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 cover read-only, idempotent, non-destructive behavior. The description adds value by disclosing the exact output boundary: 'only their cited evidence fragment, offsets, page, and confidence' and explicitly ruling out full-source returns.

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 tight sentences deliver the core behavior and a clear exclusion with no filler. The key output constraint is front-loaded and easy to parse.

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 five parameters, 0% schema description coverage, and no output schema, the description leaves too much unexplained. It conveys the output shape but omits filtering semantics, parameter meanings, and result-count behavior, so an agent would struggle to craft correct calls confidently.

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 any of the five parameters (matter_id, limit, query, fact_type, source_id). An agent gets no guidance on how to filter results, what fact_type means, or how query and limit behave.

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

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

The description names a specific operation and resource: 'Return extracted facts' with a tightly scoped output (evidence fragment, offsets, page, confidence). It clearly distinguishes this from full-source retrieval, though it does not explicitly contrast it with a 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?

The phrase 'Never returns the full source' gives a clear negative boundary for when not to use this tool, implying it is for evidence-level retrieval rather than full documents. However, it does not name alternatives or explicitly state when to prefer sibling tools like search_matter_knowledge.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds the behavioral context that the tool returns both the record and its principal relationships, and frames it as a disambiguation step. It doesn't contradict annotations and provides useful context beyond 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, no fluff, and the core action is front-loaded. The first sentence states the purpose, the second gives a concrete usage directive. 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?

For a simple single-parameter lookup with no output schema, the description is complete. It specifies what is returned (record and principal relationships), the purpose (confirm identity), and the context (before reading other data). 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 description coverage is 0%, so the description must compensate. It mentions 'matter_id' as the identifier, which clarifies the parameter's role, but it doesn't add format details or semantics beyond what the schema already states (a UUID string). For a single parameter, this is minimal but not entirely absent.

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 ('Return') and a specific resource ('the record of the Matter'), and it adds that it includes 'principal relationships'. It also distinguishes itself from siblings like get_matter_state and get_timeline by framing the tool as a way to confirm identity before other reads. This is precise and actionable for an agent.

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

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

The description explicitly says 'Use it to confirm which Matter an identifier names before reading its timeline, state or documents.' This gives a clear when-to-use scenario and implies that other tools are for the actual reads. It effectively routes the agent to the right operation.

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 cover the safety profile via readOnlyHint, idempotentHint, and destructiveHint, so the description does not need to repeat those. It adds a useful behavioral detail: the tool returns both a validated state and persisted semantic events, suggesting an event-sourced read model. However, it does not disclose error behavior, pagination, or how much history is retained.

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

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

The description is a single, front-loaded sentence with no redundancy or filler. Every word contributes to the core meaning, making it easy for an 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?

With no output schema, the description partly explains the return value but omits details an agent may need, such as how to combine or omit since and since_version, whether all changes are returned by default, and how this relates to get_matter_state or get_timeline. It is minimally viable but not fully complete for a tool operating in a sibling-rich 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 description coverage is only 33%, so the description carries some burden. It adds meaning by linking 'state version' to since_version and 'timestamp' to since, which helps. It does not clarify whether the two filters are mutually exclusive, what happens when neither is provided, or what matter_id's role is beyond being the required identifier.

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

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

The description names a specific action and resource: return the latest validated state and persisted semantic events for a matter since a version or timestamp. It is clear enough to understand the tool's core purpose, but it does not explicitly contrast itself with sibling tools like get_matter_state or get_timeline, so some differentiation is left to inference.

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?

There is no guidance about when to use this tool instead of get_matter_state, get_timeline, or get_matter. The phrase 'since a state version or timestamp' implies a filtering use case, but the description never states the intended conditions, exclusions, or alternatives.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true, and openWorldHint=false, covering core safety behavior. The description adds useful context: it returns a persisted and validated state and never reconstructs from source text, which clarifies the nature of the output beyond the annotations. This adds moderate value without 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?

The description is exactly two sentences with no redundant words. It front-loads the core purpose and adds a clarifying exclusion ('Never reconstructs...'). Every sentence earns its place; it is appropriately 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?

The tool has only one parameter, no output schema, and rich safety annotations. The description tells what it returns (a state) and that it's persisted/validated, but it does not define what the state contains or its format. Given the absence of an output schema, an agent may not know what to expect in the response, leaving a moderate gap 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 0%, and the description does not explain the single parameter matter_id. While the parameter is a simple UUID and its purpose is inferable from the tool name, the description fails to compensate for the lack of schema documentation, so the parameter semantics are only minimally clear.

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 ('Return') and a specific resource ('the latest persisted and validated Matter Intelligence state'). It also explicitly distinguishes itself by saying 'Never reconstructs state from source text', which separates it from potential tools that derive state. It doesn't name alternative tools, but the purpose is clear.

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 does not provide explicit when-to-use guidance or mention any alternative tools. The 'Never reconstructs' clause implies a negative constraint—if you need reconstruction, don't use this—but it never says 'use this when...' or 'for X, use Y instead'. An agent would have to infer usage from the name and context.

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

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

Annotations already provide readOnlyHint, idempotentHint, and destructiveHint, covering safety. The description adds valuable behavioral context by specifying the return type (dated events with stable evidence references) and a crucial boundary (never original documents). This enriches what annotations alone 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?

Two sentences with zero filler. The primary purpose and target resource are front-loaded, followed by a concise usage instruction. 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?

For a single-parameter, read-only tool with rich annotations and no output schema, the description covers the return type, a key limitation (no original documents), and the intended use case. It does not mention pagination or limits, but for a bounded timeline resource this is not a significant omission.

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

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

Schema coverage is 0% (no per-parameter descriptions), so the description must compensate. It only says 'identified by matter_id', which merely restates the parameter name. It does not explain how to obtain the ID, any constraints, or format details beyond the uuid schema. The compensation is minimal and 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 states a specific verb ('Return') and a precise resource ('analyzed timeline of the Matter'), and explicitly contrasts with 'never the original documents'. This distinguishes it from sibling tools like get_evidence or search_sources, making the tool's purpose unmistakable.

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

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

It gives a clear use case: 'Use it to answer what happened in that Matter and when.' It implies when to use this tool (chronological analysis) but does not explicitly name alternative tools or state when not to use it. The context is enough for an agent to select it appropriately.

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 annotations providing little beyond all-false hints, the description adds meaningful behavioral detail: it freezes a request rather than performing the drafting, writes no document, produces no prose, and defers to human approval. This goes beyond the annotations and clarifies side-effect boundaries, though it does not mention persistence or return 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?

Two dense sentences deliver the core action, scope, and a key exclusion without wasted words. The primary behavior is front-loaded, and each clause adds information.

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

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

The description captures the tool's central purpose and non-behaviors, which is adequate for a simple preparation tool. However, with no output schema, it omits what the tool returns (e.g., a request ID or approval artifact) and does not address preconditions or what 'freeze' means in terms of state changes, leaving meaningful gaps.

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

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

Schema description coverage is 0%, so the description must compensate. It provides some domain context ('which document, why now, which sources') that hints at the request's content, but it does not explicitly explain matter_id, attention_item_id, or instructions or how they map to the described inputs. Useful but incomplete.

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

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

The description uses a specific verb ('Freeze') and a specific resource ('a drafting request built from the matter's live state'), making the operation concrete. It also explicitly distinguishes the tool from document/prose generation by stating 'It writes no document and produces no prose,' which sets it apart from likely 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?

The description conveys the general context ('for a human to approve') and implies this is a preparation step rather than execution. However, it does not explicitly name alternatives like prepare_follow_up or prepare_matter_task, nor does it state when not to use this tool, leaving routing partially 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?

With readOnlyHint=false the annotations already flag mutation; the description adds genuinely useful negative context — 'assigns nothing' and 'never changes the item's status' — which prevents an agent from overreaching. But it does not disclose what 'freeze' concretely produces (a new draft record?), idempotency behavior (calling twice), or the approval flow's effects, which are meaningful gaps for a mutating 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 sentences with zero filler. The core purpose is front-loaded in the first sentence, and the second sentence delivers the key exclusions. Every clause earns its place.

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

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

This is a mutating tool with no output schema and 5 undocumented parameters, so the description bears a heavy burden. It covers purpose and exclusions but omits the return value, what 'freeze' produces in the system, prerequisites (e.g., item must be open), and idempotency — all relevant for an agent to call it correctly and interpret the result.

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

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

Schema description coverage is 0%, so the description must carry parameter meaning. It names assignee, due date, and note (3 of 5 params) and loosely maps attention_item_id via 'one open attention item', but it never explains matter_id's role or the matter/attention-item relationship. This is only partial compensation for the complete 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 uses a specific verb ('Freeze') with a resource ('follow-up over one open attention item') and enumerates the payload fields (assignee, due date, note). It also differentiates from siblings like prepare_matter_task and prepare_draft by explicitly stating it does not assign and never changes status — enough for an agent to tell it apart without opening the schema.

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

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

The phrase 'for a human to approve' implies the workflow context (prepare-then-approve), and the negative clauses hint that this is not the tool for assigning or mutating status. However, it never names a sibling alternative or states a when-not-to-use condition explicitly, leaving the agent to infer routing from the exclusionary phrasing.

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 adds important behavior beyond the annotations: despite readOnlyHint=false, it clarifies that no task is actually created and that persistence only happens after human confirmation. This is valuable context the annotation booleans cannot express. It could further disclose what the tool returns or how approval proceeds, but the key trait is covered.

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

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

Two compact sentences, front-loaded with the action and resource, followed by the key side-effect clarification. Every sentence earns its place and there is no redundant or promotional language.

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 adequately covers what the tool does and its no-creation behavior, but with no output schema it does not explain what the caller receives (e.g., an approval request ID or confirmation) or how to reference the prepared task later. For a 5-parameter tool with no output schema, this is a real 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?

Schema description coverage is 0%, so the description must compensate. It does mention the semantic roles of title, description, assignee, and due date as the frozen fields, but it omits matter_id and does not explain parameter behaviors beyond what the schema already shows. This is partial compensation, not complete.

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

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

The description uses a specific verb ('Freeze') and a specific resource ('internal matter task'), and enumerates the exact fields involved. It clearly distinguishes this from actual task creation by stating 'It creates nothing' and requiring human approval, which separates it from sibling prepare_* 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?

It provides clear usage context: use this to stage a task for human approval, and the task does not exist until confirmed. However, it does not explicitly name an alternative tool or provide a when-not-to-use condition, so it stops short of full guidance.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering safety. The description adds behavioral nuance: it searches 'text retained from the documents' and 'the firm's reusable memory the user can see', which clarifies scope and permission filtering. This is useful context beyond annotations, though it doesn't disclose return format or pagination.

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. The core purpose and scope are front-loaded, and the tool's target use is stated clearly. Every word contributes to understanding.

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 no output schema and 0% parameter documentation, the description covers purpose and scope but omits limit semantics and result format. While the safety profile is covered by annotations, an agent cannot fully know how to use the limit parameter or what the response will look like, so completeness is only partially achieved.

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

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

Schema description coverage is 0%, so the description must compensate for all parameters. It explains matter_id (identifies the Matter) and query (relevance), but does not explain 'limit' at all. Without any schema docs, this leaves the optional limit parameter undocumented, which is a significant gap for a tool with three parameters.

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 searches text from a Matter's documents plus firm reusable memory for query-relevant passages. It uses a specific verb ('search') and resource ('Matter's documents'), and distinguishes from siblings like search_matters (which searches matters) and search_sources (other sources) by narrowing scope to a single matter's retained content.

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

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

The description gives a clear use case: 'Use it to find what the Matter's documents say about a topic.' This implies when to use it but does not explicitly state when not to or name alternative tools. However, given sibling names and the focused scope, an agent can infer it's for document-level knowledge retrieval, not broader searches.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is fully covered. The description adds value by stating that results are limited to matters 'the current actor may see,' which implies permission/visibility filtering not present in annotations. However, it does not disclose pagination, ordering, or default behavior beyond what the schema hints at, so with annotations present this extra context earns only a moderate score.

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 concise sentences with no fluff. The primary action is front-loaded, and the return list is succinct. Every word contributes to understanding, achieving an ideal level of efficiency for a simple search tool.

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

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

For a search tool with no output schema, the description at least names the return fields, which is helpful. However, it omits how parameters interact (e.g., whether query is full-text, if status and priority are AND or OR filters, if limit has a default) and gives no hint about ordering or pagination. Given the multiple sibling search tools, a bit more detail on result scope would improve completeness, though it is not critically deficient.

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%, meaning no textual explanation accompanies the parameters. The description does not elaborate on query, status, priority, or limit semantics. It only lists return fields. Since the schema provides raw names, types, and enums but leaves the meaning of each parameter unexplained, the description fails to compensate, leaving the agent to guess how filters work.

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 ('Search the matters') and clarifies the scope ('the current actor may see'). It also lists the returned fields (identifiers, titles, status, priority, kind, opening date), making the purpose unmistakable and clearly distinct from sibling search tools like search_sources or search_matter_knowledge, which target different resource 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 gives no explicit guidance on when to choose this tool over its siblings. It does not mention alternatives, conditions for use, or contrast with search_matter_knowledge or search_sources. An agent is left to infer which search tool fits the task based on the name alone.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds a specific behavioral constraint beyond annotations: it returns no uploaded bytes and no full extracted source text. This is valuable for an agent to know upfront when deciding whether the tool satisfies its data needs.

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

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

The description is a single, front-loaded sentence that states the core purpose and immediately adds a key constraint. It contains no filler or redundancy, achieving high information density in minimal 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 search tool with 5 parameters and no output schema, the description is too thin. It does not explain query semantics, limit behavior, status or source_type valid values, pagination, or how results are ordered. The one-sentence description leaves critical details for the agent to discover through trial and error.

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% for 5 parameters (matter_id, query, limit, status, source_type). The description does not explain what any parameter means, valid values, or how to construct a search. For example, status and source_type have no type hints or enums, and the description offers zero guidance. This is a significant 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?

The description states a specific verb and resource: 'Search metadata for retained Matter sources.' It also clarifies what is not returned ('no uploaded bytes and no full extracted source text'), which helps distinguish it from content-retrieval tools. However, it does not explicitly name sibling tools, so it stops short of full differentiation.

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

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

There is no explicit when-to-use or when-not-to-use guidance. The statement 'Returns no uploaded bytes and no full extracted source text' implies that this tool is for metadata-only searches, but it does not name alternatives or conditions that would select another tool. Sibling tools like search_matter_knowledge and search_matters are not referenced.

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