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

With no annotations, the description carries the full burden. It implies a non-executing preview ('what the router *would* select'), which is a genuinely useful behavioral cue, but it never confirms the task is not executed, states cost/side effects, or describes the returned routing information.

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 short sentences, zero filler, with the core action front-loaded and the rationale second. Nothing redundant.

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

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

For a two-parameter read-only diagnostic with no output schema, this covers the essential question (does it run the task or just report routing?) implicitly well enough to call correctly. A brief note on what the response contains would make it complete.

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

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

Schema description coverage is 100%, so both parameters are already documented, and the baseline is 3. The description adds no meaning about how task phrasing affects the routing result or what agent_type changes.

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 (analyze) and resource (a task's complexity), plus the concrete result it surfaces (provider/tier the router would select). This distinguishes it from mullet_run without naming that sibling explicitly, so it is clear but not fully differentiated.

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 'useful for understanding routing decisions' implies a diagnostic/preview use case, but it never says when to call this instead of mullet_run or mullet_delegate, nor whether it must precede an actual run.

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 carry the behavioral burden. 'Query' implies a non-mutating read, and 'current' hints at fresh data, but scope (per-session vs per-project), whether it requires auth, and response shape are unstated.

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 short sentence with zero filler, front-loading the action and the two data points returned. Nothing could be removed without losing meaning.

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

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

For a no-parameter query tool with no output schema, the description minimally covers what is retrieved. It does not clarify the scope of 'token spend' or how it relates to the sibling mullet_status, leaving the agent to guess.

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

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

The tool has zero parameters, and the schema is empty, so there is nothing to document. The description correctly implies no arguments are needed to fetch spend and limits.

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 ('Query') and resource ('current token spend and budget limits'), making the read-only retrieval purpose clear. It does not explicitly differentiate itself from the many mullet_* siblings (e.g. mullet_status), so it stops short of a 5.

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

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

There is no guidance on when to use this tool versus mullet_status or mullet_analyze, and no conditions or prerequisites are given. An agent must infer that this is the budget-specific query from 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?

With no annotations, the description carries the full behavioral burden. It usefully discloses that the child agent has its own context and tools and that routing is complexity-based, but it omits side effects, permissions, lifecycle, and whether delegation is synchronous or asynchronous.

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

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

The description is two tight sentences, front-loaded with the action and followed by a concise behavioral note. There is no filler.

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

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

For a delegation tool with no output schema and no annotations, the description covers the core behavior but leaves operational gaps such as return behavior and how to track the child agent. It is adequate but not fully complete.

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

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

Schema description coverage is 100%, so the schema already documents all four parameters, including the providers allowlist. The description does not add parameter-specific meaning 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?

The description states a specific verb and resource: delegating a subtask to a Mullet child agent. It is clear what the tool does, but it does not explicitly distinguish itself from siblings such as mullet_run or mullet_swarm.

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?

Use is implied by 'delegate a subtask' and by the note that the child runs independently and is routed by complexity. However, there is no explicit when-to-use guidance, no when-not-to-use guidance, and no named 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?

With no annotations, the description carries the full behavioral burden and does: the job is gated, the cheapest passing worker is chosen, results are applied to the working tree only after gates pass, and changes are left unstaged and never committed or pushed. The enumerated status values (applied, passed_not_applied, failed, blocked, unverified, timeout) tell the agent exactly how partial success surfaces.

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, front-loaded with the 'PREFERRED' selection cue, then mechanics, then the return contract. No filler and no repetition of schema content.

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

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

For a mutating, gate-driven tool with no output schema, the description covers side effects, safety (no commit/push, unstaged), and the shape of the JSON response including status vocabulary. What is missing is cost/time implications of a full-ladder run and what 'unverified' or 'blocked' should prompt the agent to do next.

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 all six parameters are already documented, including the deprecated 'model' and the providers enum. The description adds only the ladder concept that explains why the worker cannot be chosen directly; it gives no extra detail on 'files' scoping or 'cwd' resolution beyond the schema text. 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?

Names a specific verb+resource ('runs the task as a single gated Mullet job' that edits code in the working tree) and explicitly positions itself as 'PREFERRED for code editing tasks'. That framing separates it from the analysis, delegation and search siblings without the agent opening a 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?

'PREFERRED for code editing tasks' is a clear selection directive, and the gating/applied-only-after-pass behavior tells the agent what kind of work belongs here. It stops short of naming the alternatives it beats (mullet_run, mullet_delegate, mullet_swarm), so the agent still has to infer 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 are provided, so the description carries the full burden. It discloses that it lists providers and includes health status, but does not describe read-only behavior, permissions, return format, or any side effects. For a zero-parameter read tool this is minimally adequate but thin.

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 sentence, front-loaded with the main action and resource, 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?

For a simple zero-parameter listing tool with no output schema, the description covers what the tool returns in broad terms. It could be slightly more complete by mentioning the output shape or freshness of health status, but it is largely 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 tool has zero parameters, so there is no parameter semantics to explain. The baseline for a zero-parameter tool is 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 states a specific verb ('List') and resource ('LLM providers'), plus the additional scope of health status. It does not explicitly differentiate itself from any sibling, but no sibling appears to offer provider listing, so the purpose is clear enough.

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 by the description — call it to see providers and their health — but there is no explicit guidance on when to use it versus alternatives 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 are provided, so the description carries the full behavioral burden. It implies a write but says nothing about key-collision behavior (overwrite vs. error), durability scope (per project? per client?), required permissions, or what is returned on success.

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 front-loaded sentence with the verb first and zero filler. It is efficient; the problem is under-specification, not verbosity.

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 no annotations and no output schema, the description should explain persistence semantics and overwrite behavior. With three required parameters and a near-identical sibling, the current one-liner leaves real decision 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 100% and all three parameters are required and documented there. The description adds no meaning beyond the schema — notably it does not clarify what a 'trove client' is or how it scopes the stored memory — so the baseline 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?

States a specific verb ('Store') and resource ('a memory in a project's knowledge base'), so the agent knows exactly what the call produces. It does not, however, distinguish itself from sibling trawl_memory_store, which appears to do the same thing.

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?

'for future sessions' hints at the intent (persistence across sessions) but there is no explicit when-to-use/when-not guidance. Critically, the sibling trawl_memory_store is an apparent duplicate and the description gives no basis for choosing between the two.

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 behavioral burden. It usefully discloses that no files are written and that routing is provider- and complexity-based, but it does not address return behavior, execution time, cost implications, authentication, or whether the call is synchronous. These omissions are significant for a nine-parameter task-execution tool.

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

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

Three tight sentences, each earning its place: the first prevents misuse by routing code-editing tasks to mullet_opencode, the second defines the allowed use cases, and the third explains provider routing. It is front-loaded and free of 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?

The description is strong on usage boundaries and sibling differentiation, which is important given the large sibling set. However, with no annotations and no output schema, it does not explain what the tool returns or how results are delivered, leaving a notable gap for a complex execution tool. The schema covers parameters, but behavioral completeness is only partially addressed.

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 input schema already documents all nine parameters in detail. The description adds only the high-level routing context based on complexity, which aligns with the tier parameter but does not add meaningful semantics beyond the schema. The baseline of 3 is appropriate.

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

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

The description clearly states the tool's scope: analysis, planning, research, review, or text generation tasks where no files need to be written. It explicitly distinguishes this tool from mullet_opencode, which handles code editing, and notes that it routes to the optimal provider based on complexity. An agent can identify both what the tool does and what it does not do.

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 explicit when-to-use and when-not-to-use guidance, naming the alternative mullet_opencode for code editing and listing the exact task categories appropriate for mullet_run. The exclusion is front-loaded and unambiguous, leaving little inference required.

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 the full behavioral burden. It implies a read operation and names a 'hybrid search engine', but discloses nothing about permissions/auth, ranking behavior, result shape, or whether top_k is capped; a hybrid semantic+lexical search merits at least a note on how results are ranked or returned.

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 short sentences with the core purpose front-loaded and no filler. The second sentence on the hybrid engine adds a small amount of ranking context but is not strictly 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?

With no output schema and no annotations, the description should convey what results look like and how they are ranked. It omits return format and any scoping/auth notes, leaving a meaningful gap for an agent trying to 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 query, top_k, and client are already documented in the schema, which sets the baseline at 3. The description adds no extra meaning (e.g., what 'client' project scope entails or relevance of top_k) beyond what the schema already provides.

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 (Search) and resource (project knowledge) with a stated goal (relevant context), scoped by a project/client. Clear enough on its own, but it does not distinguish itself from the many sibling search tools (trawl_search, trawl_memory_search, trawl_search_entities) in the environment.

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, when-not-to-use, or alternative guidance. With dozens of overlapping search siblings, an agent is left to infer when mullet_search is the right pick over trawl_search or trawl_memory_search.

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

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

No annotations are provided, so the description carries the full burden. It discloses the information returned (active tasks, provider health, budget), which implies a passive read, but never confirms it is side-effect free, whether it triggers any polling/refresh, or how costly a call is.

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

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

One sentence, front-loaded with the action, followed immediately by the payload facets. No filler or redundancy.

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

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

With no annotations and no output schema, the description is the only source of return-value and safety context. Listing the three facets gives a rough shape, but the actual response format and read-only nature are not described, leaving the agent to guess at what a call returns.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate; the baseline for a parameter-free tool 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?

States a specific verb and resource ('Check Mullet's current status') and enumerates the reported facets: active tasks, provider health, budget. It does not explicitly differentiate itself from siblings like mullet_budget or mullet_providers, which cover overlapping facets individually, so it stops short of a 5.

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

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

The phrase 'current status' implies a quick health/overview check, but there is no explicit when-to-use, when-not-to-use, or pointer to the narrower mullet_budget / mullet_providers tools it overlaps with. Usage is inferable but not stated.

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 disclosure burden, and it omits the important traits: that this dispatches many paid model calls (cost/concurrency implications), that a dry_run plan mode exists, that partial failures are possible, and that it does not edit files. The safety and side-effect profile is entirely unstated.

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, zero filler, with the core action front-loaded and the usage criterion immediately after. Nothing repeats the schema or title.

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 an 8-parameter orchestration tool with no annotations and no output schema, the description says nothing about what the synthesized result looks like, how the task plan differs under dry_run, or what the caller receives. The agent must infer all behavioral and output expectations from the schema alone.

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 every parameter including the deprecated 'apply' and 'dry_run' is already documented in the schema, establishing the baseline of 3. The description only loosely echoes the files/items split with "multiple files, items" and adds no format or behavioral detail 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 gives a specific verb pair (fan-out, synthesize) and the mechanism (parallel Kimi K2 calls) applied to a named input (goal). It is clear what the tool does, though it does not explicitly name a sibling such as mullet_run or mullet_delegate to differentiate itself from the other mullet orchestration 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?

"Use for tasks that can be split across multiple files, items, or independent sub-questions" gives a concrete selection criterion an agent can apply. It stops short of stating when NOT to use it or pointing to the alternative (e.g., mullet_opencode for edits), so there are 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 must carry the full behavioral burden. It implies a read operation and notes that the system prompt is included, but it does not clarify permission needs, failure behavior, or what the returned config contains beyond that single field.

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 with the action and key return content front-loaded. There is no filler 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 one-parameter getter with full schema coverage, the description is adequate to call the tool. However, with no output schema it only vaguely describes the return as full config including the system prompt, and it lacks sibling differentiation.

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 sole agent_name parameter is documented in the schema as an agent name or filename slug. The description adds no parameter-specific meaning beyond what the schema already provides, 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?

The description states a specific verb and resource: it gets an agent template's full config, explicitly including the system prompt. This is clear enough to distinguish it from broad list/search tools, but it does not explicitly contrast with sibling tools such as trawl_agents_list or trawl_run_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 gives no explicit when-to-use guidance, prerequisites, or alternatives. An agent can infer this is for retrieving one agent's config, but there is no routing guidance versus trawl_agents_list or trawl_run_agent.

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 whole burden. 'List available' implies a safe read, but it says nothing about result volume, pagination, ordering, or what an 'agent template' actually contains, and there is no output schema to fill that 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?

One short sentence with the resource front-loaded and the optional modifier trailing; nothing is wasted, though it is arguably too thin rather than optimally sized.

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 is simple (one optional param, no nested objects), so a single sentence is close to sufficient. But with no annotations and no output schema, the agent gets no signal about return shape or whether the list can be large.

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 single parameter is already documented as 'Filter by tag'. The description merely restates that the filter is optional, adding no syntax, matching behavior, or case-sensitivity detail 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?

States a specific verb (List) and resource (agent templates) with an optional filter. It is distinguishable from trawl_agents_get and trawl_run_agent by the enumeration framing, though it never names those siblings 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?

The phrase 'optionally filtered by tag' implies the discovery use case, but there is no explicit guidance on when to prefer this over trawl_agents_get or trawl_run_agent, nor any prerequisite or exclusion stated.

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 does disclose that the job 'runs in background', which is genuine behavioral value (call returns before completion). It does not say what is returned (job id?), how to track progress, cost/duration, or what happens to an existing graph when rebuild is false.

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 short, front-loaded sentences with no filler. The brevity is close to under-specification, but nothing present is wasted.

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 an asynchronous, potentially expensive mutation job with no annotations and no output schema, so the description should explain the return value (job handle), progress tracking, and side effects on existing graph data. It gives only 'runs in background', leaving an agent unable to know how to follow up.

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 each of the five parameters is already documented, including the provider allowlist and sample limit. The description adds nothing beyond the schema, so baseline 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?

States a specific verb (build/rebuild) and resource (knowledge graph), which distinguishes it from siblings like trawl_graph_stats, trawl_graph_export, and trawl_graph_prune. However, the phrase 'for a client' does not match the required parameter 'pool_name', leaving a small ambiguity about what is being built.

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 indication of when to use this versus trawl_reindex_pool, trawl_sync_pool, or trawl_graph_stats, and no prerequisites or exclusions are given. The only guidance is the implicit 'rebuild' semantics already in the schema.

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 behavioral burden and does not meet it: it says nothing about GitHub authentication/token requirements, whether connecting triggers an immediate crawl/index, whether the operation is idempotent, or what happens if the owner is already connected. 'Add ... as a source' implies mutation but discloses no side effects or safety profile.

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 front-loaded sentence with no filler; the action and target are stated immediately. It is efficient but borders on under-specification given the tool's complexity.

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 5-parameter mutation tool with no annotations and no output schema, the description omits essential context: auth needs, whether ingestion/sync happens automatically, and expected outcome. Sibling tools handle the follow-up discovery, but the agent is not told any of that.

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 explains owner, repo, pool_name, and the include/exclude lists, making 3 the baseline. The description's phrasing ('account, org, or repo') loosely maps to the owner/repo distinction but adds no syntax, format, or interaction details (e.g. how include_repos and exclude_repos conflict) 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 gives a specific verb ('Add') and resource ('GitHub account, org, or repo as a source for a pool'), which is clearly distinguishable from sibling source-management tools like trawl_list_sources and trawl_sync_sources. It stops short of naming those siblings or clarifying how this differs from trawl_crawl_web/ingest tools, but the core action 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?

There is no guidance on when to use this versus trawl_sync_sources, trawl_list_sources, or trawl_ingest_url, nor any prerequisites (e.g. must the pool already exist?). The agent must infer usage entirely from the tool name and schema.

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 at all, the description carries the full burden, yet it does not disclose that this performs network I/O and writes many pages, how long a crawl may take, whether existing pages are overwritten, or what happens on partial failure. Only the Markdown output destination is conveyed, and even that ('for a client') is ambiguous.

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

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

One sentence with no padding is good front-loading, but it is under-specified rather than concise, and the trailing 'for a client' phrase adds confusion rather than 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 multi-parameter, network-facing write tool with no annotations and no output schema, the description is far too thin: it omits crawl scope, pool semantics, limits, and return/failure behavior, leaving the agent to infer almost everything.

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 most parameter meaning comes from the schema itself and baseline 3 applies. The description adds nothing about pool_name (the schema merely says 'Pool name') or crawling scope beyond what stay_in_path and max_pages already declare.

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 plus resource plus outcome: crawl a website and save pages as Markdown. An agent can tell what it does, but nothing distinguishes it from siblings like trawl_ingest_url, and the phrase 'for a client' is unexplained.

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 on when to choose this over trawl_ingest_url or the search/ingest family, no preconditions (does the pool need to exist?), and no exclusions. An agent must guess from the sibling 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?

With no annotations, the description must carry the load; it does disclose the multi-source fallback chain (Context7 -> Trawl pools) and that results are version-aware, which is real behavioral context. It says nothing about result format, latency/rate limits, or what happens when no source matches.

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: capability first, usage condition second. No filler, no restating of the name, and the important mechanism (version-aware, fallback) 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?

For a read-only lookup tool with fully described parameters and no nested objects, the description covers what it does and how sources are prioritized. The only meaningful omission is what the returned content looks like (doc excerpts vs. links), since there is no output schema.

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

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

Schema coverage is 100%, so query, library, sources, and version are already documented with examples. The description adds only the framing that lookups are version-aware and source-ordered, which is largely restated by the schema's defaults.

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 (look up) and resource (documentation for a library), plus the underlying mechanism (Context7 with local Trawl pool fallback). That clearly separates it from generic sibling tools like trawl_search or trawl_search_code, though it never names those siblings as the contrast.

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?

"Use this when you need API docs, usage examples, or version-specific information for any library" gives an explicit triggering condition. It stops short of when-not-to-use guidance (e.g., use trawl_search_code for source inspection or trawl_search for non-library material).

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 behavioral burden, and it discloses almost nothing: matching semantics (exact vs partial/fuzzy), default search scope across pools, result limits, and behavior when no match is found are all unstated. For a search tool with zero annotation coverage, this is thin.

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 front-loaded sentence with the action and resource first and zero filler. It is efficient, though its brevity borders on under-specification rather than true 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?

With four parameters, no annotations, and no output schema, the description should cover match semantics, scope across pools, and result shape. It covers none of these, leaving an agent guessing about how the search actually behaves.

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 all four parameters are already documented in the schema; the description only restates the symbol-type examples. Baseline 3 applies since the schema does the heavy lifting and the description adds no extra semantics such as matching behavior for symbol_name or pool defaulting.

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?

Clear verb+resource: 'Find a specific code symbol' with parenthetical examples (function, class, variable) and the lookup key 'by name'. However, it does not distinguish itself from close siblings like trawl_search_code or trawl_search_entities, which an agent could easily confuse with this symbol lookup.

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 'by name' implies this is the exact-name lookup path, and requiring symbol_name reinforces that, but there is no explicit statement of when to prefer this over trawl_search_code / trawl_search_entities, and no 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?

No annotations are provided, so the description carries the full burden. The word "get" implies a read, but the description says nothing about what happens if no pool is loaded (error vs. empty result), whether the call has any side effects, or the shape of the response.

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 front-loaded sentence with no filler. It is efficiently sized, though the brevity reflects under-specification rather than tight editing.

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, no annotations, and no parameters, the description is the only source of information about behaviour — and it does not indicate what 'information' is returned or the failure mode when no pool is loaded. For a status-style tool this leaves 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?

The tool takes zero parameters, so there is nothing for the description to disambiguate. Baseline 4 applies since no parameter semantics are needed.

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

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

"Get information about the currently loaded pool" names a verb (get) and a resource (pool), and the qualifier "currently loaded" hints that it targets one specific pool rather than a collection. But "information" is opaque — it never says what data is returned, and it is not differentiated from near-neighbours like trawl_graph_stats, trawl_ingest_status, or trawl_list_pools.

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 when-to-use guidance, no mention of an alternative such as trawl_list_pools for enumerating pools, and no stated prerequisite that a pool must already be loaded via trawl_load_pool. The only usage hint is the phrase "currently loaded," which the agent must interpret itself.

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 behavioral burden. It implies a read-like export and specifies the JSON format, but does not disclose whether the operation is safe/read-only, how max_nodes affects completeness, permission requirements, or failure 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?

It is a single, front-loaded sentence with no wasted words. The core action, resource, and output format are stated immediately.

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

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

For a low-complexity export tool with only two optional, fully documented parameters and no output schema, the description is mostly complete. It states the output format, though it could mention the default scope or behavior when pool_name is omitted.

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

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

Schema description coverage is 100%, and the schema already documents both parameters (max_nodes default 500, pool_name). The description does not add parameter-specific meaning beyond what is structured, so the baseline 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 states a specific verb and resource: export the knowledge graph as D3.js-compatible JSON for visualization. It is clear what the tool does and its output format, though it does not explicitly distinguish itself from sibling graph tools such as trawl_graph_stats or trawl_build_graph.

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 guidance on when to use this tool versus alternatives, nor does it state prerequisites or exclusions. Usage is only implied by the word 'Export' and the visualization purpose.

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 carry the full behavioral burden. It does disclose what gets destroyed and scopes it to genuinely orphaned records, which is valuable, but omits irreversibility, whether a dry-run or confirmation exists, counts of removed items, and permission requirements.

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 front-loaded sentence with zero filler; the destructive scope is stated before any qualifier. Nothing could be cut without losing 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 an unannotated mutation tool with no output schema, the definition covers what is deleted but not the response shape, reversibility, or required permissions. An agent can call it correctly but cannot predict consequences or 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?

Only one parameter (pool_name) with 100% schema coverage, so the schema already fully documents it. The description adds no parameter-level meaning, such as noting that pruning applies only to the named pool's collection — baseline 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?

States a specific verb (Remove) and enumerates the exact resources pruned: orphaned entities, relationships, and processed-chunk tracking. The 'orphaned … whose source chunks no longer exist' qualifier distinguishes it from broader destructive siblings like trawl_pool_delete, though it doesn't explicitly name them.

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 only implied through maintenance framing — an agent can infer this is post-deletion garbage collection. There is no explicit when-to-run guidance, no contrast with trawl_reindex_pool or trawl_sync_pool, and no note on whether a rebuild is a preferred alternative.

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 disclosure burden; 'Get' implies a non-destructive read, and it names the returned metrics, which is useful since there is no output schema. However, it says nothing about required permissions, cost, or what happens when a pool has no graph, which are meaningful gaps for an unannotated 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?

A single, front-loaded sentence naming the resource first and the returned statistics parenthetically. No filler, though it could also have used the space for scoping or prerequisite 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 one-parameter read tool with no output schema, listing the metric categories gives the agent a reasonable expectation of the return value. The remaining omission is the pool prerequisite, which is minor for this complexity level.

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% (one required parameter, pool_name), so the schema already carries the parameter documentation and baseline 3 applies. The description adds no extra meaning about the pool_name argument, such as whether it must be an existing indexed pool.

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?

Names a specific verb (get) and resource (knowledge graph statistics) and even enumerates what the stats cover (node/edge counts, entity types). It is clearly distinct from siblings like trawl_build_graph or trawl_graph_export, though it never says so 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?

There is no statement of when to call this versus alternatives such as trawl_build_graph, trawl_graph_export, or trawl_get_pool, and no prerequisites (e.g., whether the pool must be built first). Usage is only inferable from the name and the word 'statistics'.

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 behavioral burden. It does not disclose side effects, whether ingestion is synchronous or asynchronous, what happens if the pool does not exist, or what the success/failure behavior looks like.

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 wasted words. However, the typo "pool.s" and the extremely terse phrasing keep it from being fully polished.

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 that there are no annotations and no output schema, the description is not complete enough for an ingestion/mutation tool. It omits key operational context such as required permissions, pool existence assumptions, supported file types, and ingestion 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 description coverage is 100%, so both file_path and pool_name are already documented in the schema. The description adds no parameter-level detail beyond naming the file and target pool, so the baseline of 3 is appropriate.

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

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

The description gives a specific verb and resource: "Ingest a single file into a pool's collection." This distinguishes it from sibling tools like trawl_ingest_url, but the typo "pool.s" slightly reduces clarity and there is no explicit sibling comparison.

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 explain when to use this tool versus alternatives such as trawl_ingest_url, trawl_load_pool, or trawl_ingest_status. It only implies usage through the phrase "single file," with no prerequisites or 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 carries the full burden. It implies a read-only lookup but never states that, nor does it describe return shape, whether statuses are terminal (running/complete/failed), polling cadence, or what happens when the job is unknown.

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

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

One sentence with no wasted words and nothing to trim, but it is under-specified rather than concise — brevity comes at the cost of missing operational detail.

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 annotations and no output schema, the description must explain both safety profile and what a status result looks like, and it does neither. It also leaves the job_id vs pool_name relationship (both optional, 'alternative to') unclarified.

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

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

Schema description coverage is 100%, and the schema already explains both job_id (with its originating tool) and pool_name as an alternative. The description adds nothing beyond the schema, so the baseline 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?

States a specific verb and resource: 'Check the status of an ingestion job.' An agent can tell this is a status/polling tool, distinct in kind from trawl_ingest_file or trawl_ingest_url. It does not distinguish itself from trawl_workflow_status or mullet_status, which serve the same status-checking purpose for different resources.

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 call this versus alternatives, how often to poll, or what to do once a job reaches a terminal state. The only routing hint is a parameter description pointing back to trawl_reindex_pool, which is in the schema, not the description.

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 behavioral burden. It does not disclose whether ingestion is synchronous or asynchronous, how to check progress (trawl_ingest_status exists), whether existing content in the pool is overwritten, or what errors or limits apply.

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?

It is a single front-loaded sentence with no padding, but it is under-specified rather than genuinely concise, and the typo 'pool.s' slightly reduces clarity. It is efficient in length but wastes the little space it has.

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/ingestion tool with no annotations and no output schema, the description should explain return behavior, status tracking via trawl_ingest_status, and how it relates to sibling ingestion tools. None of that is present.

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

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

Schema description coverage is 100%, and both parameters (url, pool_name) are documented in the schema. The description adds no extra meaning beyond what the schema already provides, so the baseline 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?

States a specific verb and resource: 'Ingest content from a URL into a pool.' An agent knows the basic action without opening the schema. However, it does not differentiate from close siblings like trawl_ingest_file, trawl_crawl_web, or trawl_sync_pool, so it falls short of a 5.

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

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

There is no guidance on when to use this tool instead of trawl_ingest_file (for local files), trawl_crawl_web, or trawl_sync_sources, nor any preconditions such as pool existence or authentication requirements. Usage is only implied by the tool name.

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; 'List all' implies a non-destructive read, but ordering, pagination, and whether 'all' is scoped to the caller's client are unstated. The domain gloss about per-client indexed collections is genuine added context beyond the name.

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 short sentences, with the core purpose front-loaded and a single clarifying clause after it. Nothing is wasted.

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

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

For a zero-param discovery tool with no output schema, the description should sketch what a returned pool looks like (id/name) since those values feed trawl_load_pool and trawl_search_pool. As written it is adequate but leaves the agent guessing about the return shape and follow-up 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?

The tool takes zero parameters, so the baseline is 4; there is nothing for the description to disambiguate.

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 and resource ('List all available knowledge pools') and adds a gloss on what a pool is. It does not explicitly contrast with siblings such as trawl_get_pool or trawl_load_pool, but the name-plus-description 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?

Usage is only implied: the note that each client has its own collection hints that a pool must be chosen before searching or loading, but the description never says when to call this versus trawl_get_pool / trawl_load_pool, nor any 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 at all, the description carries the full behavioral burden but supplies almost nothing: no statement that it is a read-only operation, no pagination or result-cap behavior, no behavior on an unknown pool (empty list vs error). Only the word 'indexed' hints that results are limited to already-ingested repos.

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 front-loaded sentence with no filler. It is efficient, though efficiency here reflects under-specification rather than disciplined editing.

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

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

For a one-parameter listing tool with no annotations and no output schema, the description should say what a returned repo entry looks like (name? owner? URL?) and whether results are bounded. Neither is covered, so an agent knows the intent but not the shape of 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 coverage is 100% so the baseline is 3, but the schema text itself is only 'Pool name', and the description's 'for a client' actively muddies the meaning of pool_name rather than clarifying it. No explanation of where a pool name comes from or how it relates to clients.

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 verb+resource ('List GitHub repos indexed') is concrete, but 'for a client' introduces a term that matches neither the parameter (pool_name) nor any sibling tool vocabulary, leaving the scoping ambiguous. It also does not distinguish itself from nearby siblings such as trawl_list_sources, trawl_list_pools, or trawl_search_repo.

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 on when to use this versus trawl_search_repo (search within a repo) or trawl_list_sources (list sources). No prerequisites, no exclusions, no indication of what a caller should do after listing.

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 of behavioral disclosure. It implies a read-only listing operation but does not state permissions, pagination, ordering, or whether sources are scoped strictly by pool. For a list tool with no annotation coverage, this is notably thin.

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 with no filler. It is front-loaded and appropriately sized, though the phrase 'for a client' introduces ambiguity rather than useful structure.

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 annotations and no output schema, the description should explain more about what a 'source' is and what the listing returns. It does not clarify whether the list is filtered by pool, client, or both, nor does it mention permissions or result shape. It is insufficient for an agent to invoke the tool with full confidence.

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 even though the description adds no parameter detail. The schema itself describes 'pool_name' only as 'Pool name', and the description does not clarify how this relates to 'client', so there is some ambiguity but no direct contradiction.

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

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

The description states a specific verb ('List') and resource ('document sources'), which is clearer than the tool name alone. However, it says sources are 'for a client' while the required parameter is 'pool_name', creating ambiguity about scope. It also does not distinguish this tool from nearby siblings such as trawl_list_repos, trawl_list_pools, or trawl_sync_sources.

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 indication of when to use this tool versus alternatives like trawl_list_repos or trawl_sync_sources. The description gives a bare purpose statement with no usage context, prerequisites, or 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 carries the full behavioral burden. It hints that loading affects future searches, but does not disclose whether the selected pool is session-scoped or global, whether it replaces a prior pool, what happens if the pool does not exist, or what permissions are required.

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 wasted wording. It states the action and its downstream purpose immediately.

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 is low-complexity in parameter count, but it appears to change search context and has no annotations or output schema to explain that behavior. The description is therefore missing important state-management details an agent would need before invoking 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?

Schema description coverage is 100% and the single required parameter is documented in the schema, so the baseline is 3. The description adds little beyond "specific pool," and the schema's "Name of the client to load" wording is not clarified.

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 ("Load") and resource ("pool") and adds the effect "for subsequent searches," so the agent can understand it selects a search context. It does not explicitly distinguish itself from nearby siblings such as trawl_get_pool or trawl_search_pool, which keeps it below a 5.

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

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

The phrase "for subsequent searches" implies when the tool is useful, but it does not state when-not to use it or name alternatives like trawl_get_pool, trawl_list_pools, or trawl_search_pool. Usage is inferable rather than explicitly guided.

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 behavioral burden. It says "Delete" but does not disclose whether deletion is permanent, what permissions are required, whether the operation is reversible, or how pool scope affects deletion.

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 wasted words. It states the action and the primary identifiers efficiently.

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

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

For a low-complexity tool with full schema coverage and no output schema, the description is minimally adequate. However, as a delete operation with no annotations, it should provide more context about irreversibility or safety implications.

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 input schema already documents key, namespace, and pool_name. The description mentions namespace and key but adds no syntax, default, or scope details 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: "Delete a memory by namespace and key." It is clear which operation this tool performs, though it does not explicitly distinguish itself from sibling tools such as trawl_memory_store or trawl_memory_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?

The description gives no guidance on when to use this tool versus alternatives like trawl_memory_store, trawl_memory_search, or trawl_memory_list. It only states the operation, leaving usage context implicit.

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 the full behavioral burden and delivers little: nothing about read-only safety, result limits, ordering, pagination, or what happens when the memory store is empty. It also ignores the pool_name scope parameter entirely, which matters because omitting it silently means 'global'.

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 front-loaded sentence with zero filler. It is efficient, though the brevity is partly the under-specification problem rather than disciplined compression.

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 optional-parameter read tool this covers the basics, but with no output schema and no annotations an agent still lacks the return shape (memory fields, ordering, size limits) and the pool scoping behavior. Adequate, with clear 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 100%, so both parameters are already documented and a baseline of 3 is warranted. The description restates namespace filtering but adds nothing about pool_name semantics ('global if omitted'), so it does not enrich 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?

States a specific verb and resource: 'List all stored memories', with the scope qualifier 'optionally filtered by namespace'. It is clearly an enumeration tool, which implicitly contrasts with trawl_memory_search, but it never names that sibling to make the distinction explicit.

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 'optionally filtered by namespace' implies the main usage context, but there is no statement of when to prefer this over trawl_memory_search (which presumably queries by content) or when not to use it. No prerequisites or exclusions are 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 are provided, so the description carries the full disclosure burden, yet it only says the search is semantic. It omits ranking/ordering behavior, default result count behavior, what happens when namespace or pool_name are omitted, whether results span pools, and whether the operation is read-only or touches state.

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 front-loaded sentence with zero filler or repetition. It is efficient, but the brevity crosses into under-specification for a four-parameter tool with no annotations.

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 four parameters, no annotations, and no output schema, the description should explain the memory/pool/namespace model and how results are ordered, but it does none of that. An agent can form the call from the schema but cannot predict what it will get back or how scoping interacts.

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 all four parameters (query, top_k, namespace, pool_name) are already documented in the schema. The description adds only the word 'semantically', which implies the query is matched by embedding similarity rather than keywords — a small but real signal 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?

States a specific verb (search) and resource (stored memories) plus the retrieval mode (semantically), so the agent knows this is semantic retrieval over the memory store rather than code or graph search. It does not distinguish itself from neighbors like trawl_memory_list, trawl_search, or trawl_search_pool, so an agent must infer the boundary.

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 when-to-use guidance at all: nothing says whether to reach for this versus trawl_memory_list (enumeration) or the generic trawl_search, and no prerequisites or exclusions are given. The agent has to guess 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?

No annotations are provided, so the description carries the full burden for a write operation. 'Semantic search capability' hints that stored content is indexed/embedded, but it says nothing about what happens on a duplicate key (overwrite vs. error), durability, indexing latency, or what is returned after a store.

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 front-loaded sentence with no filler. It is appropriately sized, though the brevity partly reflects missing information rather than disciplined editing.

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

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

For a six-parameter mutation tool with a nested metadata object, no annotations, and no output schema, the description is thin. Key-collision behavior, indexing side effects, and post-store state are all unaddressed and must be inferred by the agent.

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 all six parameters including ttl, namespace default, and pool_name scope are already documented in the schema. The description adds no syntax, format, or interaction detail beyond that, making the baseline 3 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 verb 'Store' plus the resource 'memory/note' make the operation clear and distinct from siblings like trawl_memory_search and trawl_memory_list. It never explicitly names an alternative or states the boundary, so it stops short of a 5.

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

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

There is no guidance on when to use this versus trawl_memory_search, trawl_memory_list, or the overlapping mullet_remember sibling, and no prerequisites or exclusions are given. Usage must be inferred entirely from the tool name.

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 present, the description carries the full burden and does well: it explicitly discloses irreversibility ('Permanently') and that both the directory and the index are destroyed, plus the confirm safety gate. It stops short of describing side effects such as whether search results, graphs, or memory entries tied to the pool are also affected.

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 short sentences with zero filler; the destructive nature and scope come first and the safety prerequisite second. 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 two-parameter destructive tool with no output schema and no annotations, the description covers what an agent most needs: that it is irreversible, what gets removed, and that confirm must be set. Minor gaps remain around error behavior when the pool does not exist and permissions required.

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

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

Schema description coverage is 100%, so both parameters are already documented in the schema, including 'confirm: Must be true to actually delete.' The description only restates the confirm requirement and adds nothing about pool_name semantics (e.g., whether the name must exactly match an existing directory). 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?

States a specific verb and resource ('Permanently delete a Trawl pool') and clarifies the scope of what is removed ('directory + index'). This clearly separates it from sibling pool tools such as trawl_list_pools, trawl_get_pool, and trawl_load_pool.

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 hard prerequisite ('Requires confirm=true'), which is genuinely useful usage guidance. It does not, however, say when this should be used versus alternatives (e.g., whether there is any non-destructive removal path or what to do before deleting), so guidance is implied rather than complete.

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 behavioral burden, and it discloses almost nothing. It does not say how local and live results are merged or de-duplicated, whether the live call has latency/failure/rate-limit implications, or what the response looks like.

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 front-loaded sentence with no filler, and the differentiating detail (local + live) comes first. It is efficient, though its terseness leaves gaps that the conciseness score itself should not penalize.

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 annotations and no output schema, the description should explain result shape, ranking/merge behavior, and failure modes of the live component. None of that is present, leaving an agent unable to predict what it gets back or how costly the call is.

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 every parameter (type enum values, query, top_k default and max) is already documented in the schema. The description adds no extra parameter meaning such as matching semantics or how top_k applies across the two sources, so baseline 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?

States a specific verb (Find) and resource (prompts) and adds the key distinguishing trait that it merges a local index with a live API search. This implicitly separates it from trawl_prompts_search_live, though it never names that sibling or states the relationship 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?

Usage is only implied: because it combines local and live sources, an agent can infer it is the broadest prompt-search option. There is no explicit 'use this when...' or 'use trawl_prompts_search_live instead when...' guidance, despite several plausible alternatives in the sibling 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?

No annotations are provided, so the description carries the full burden and it does not disclose error behavior for an unknown prompt_id, how missing variables are handled, or whether substitution is strict or lenient. It only conveys that a substitution step exists.

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

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

One front-loaded sentence covering resource, identifier, and the optional substitution capability, with no filler. It is efficient though quite terse for a tool with no annotations to fall back on.

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 should say what comes back (rendered text vs. raw template plus metadata) and how substitution failures surface. It leaves both unanswered, so an agent knows what to send but not what to expect.

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 parameters are already documented and the baseline is 3. The description adds only the notion that 'variables' is optional substitution rather than anything about matching keys to placeholders.

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: fetch a single prompt template by ID, with optional variable substitution. This is distinguishable from the search-style siblings (trawl_prompts_find, trawl_prompts_search_live), but the description never explicitly names them to sharpen the contrast.

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 'by ID' phrasing implies it should be used when a prompt_id is already known and that lookup/search belongs to a sibling, but no explicit when/when-not guidance or alternative is named. An agent must infer the routing.

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

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

No annotations are provided, so the description carries the full behavioral burden, and it discloses almost nothing: no indication of auth requirements, rate limits, whether results are live or cached, or what the response looks like. The word 'live' in the tool name hints at an external call but the description never confirms or explains it.

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 front-loaded sentence with no filler, so nothing is wasted. It is efficient but so terse that brevity crosses into under-specification.

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 six parameters, no annotations, and no output schema, the description should at minimum sketch the return shape and clarify the difference from related prompt tools. One sentence leaves an agent guessing on the essentials.

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 all six parameters (query, tag, sort, type, limit, category) are documented in the schema itself, so the baseline is 3. The description adds no extra meaning such as how filters combine or what empty results look like.

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 gives a clear verb ('Search') and resource ('prompt templates') scoped to the prompts.chat API, which is more than a tautology. However, it does nothing to distinguish this tool from the sibling 'trawl_prompts_find', leaving the agent unable to tell which search entry point to pick.

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 when-to-use guidance, no mention of prerequisites (API key, network access), and no reference to the alternative 'trawl_prompts_find' or 'trawl_prompts_get'. The agent must infer context from 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?

With no annotations, the description carries the burden and does disclose the non-obvious behavior: the sort key falls back through published date, PDF creation date, crawl first-seen, and text-changed time. It does not cover what a returned document contains (full text vs. snippet), whether results are truncated or paginated beyond `limit`, or cost/latency, so it falls short of full 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?

Two sentences, front-loaded with the action and ordering, then the routing rule. The four-item date enumeration is dense but each item earns its place by defining the ordering the agent must reason about.

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 3-parameter read-only listing with no output schema, the description covers what is listed, how it is ordered, and when to prefer it. It stops short of describing the response shape or pagination behavior, which an agent might want when requesting `limit: 100`.

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, but the description adds real meaning by defining which date the `since` cutoff is compared against (the 'best date known'), which the schema's one-line description does not clarify. `limit` and `pool_name` add nothing 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?

States a specific verb and resource — 'List a pool's documents newest first' — and immediately explains what 'newest' means via the four date sources. It is clearly distinguishable from the many trawl_search* siblings because it is a listing ordered by date, not a query-ranked retrieval.

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 routes the agent: 'Use this, not search, for "what's new" / "recent news" questions.' Names the alternative (search) and the condition that selects this tool, with concrete example phrasings an agent can pattern-match.

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 behavioral burden, and 'Runs in the background' is a genuinely useful disclosure that the call is asynchronous and returns before completion. But it omits whether the operation destroys/rebuilds the existing index, whether it is idempotent, whether concurrent reindexes are blocked, and how to track progress (e.g., via trawl_ingest_status).

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 short sentences, front-loaded with the action and followed immediately by the key behavioral fact. Nothing is padding and nothing important is buried.

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-style background job with no annotations and no output schema, the description is too thin: it says nothing about cost/duration expectations, whether the index is unavailable during the run, or how to confirm completion. Given the density of overlapping pool/ingest siblings, an agent needs more to call this safely and 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%, and the schema already documents pool_name as 'Name of the client to reindex'. The description's phrasing ('a client's documents') confirms the semantic link but adds no format, naming convention, or validation detail beyond the schema. Baseline 3 applies when the schema does the heavy lifting.

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 ('Trigger a full reindex') and resource ('a client's documents'), so the operation is unambiguous. It does not, however, distinguish itself from overlapping siblings such as trawl_sync_pool, trawl_load_pool, or trawl_ingest_file, leaving the agent to infer what 'reindex' means versus 'sync'.

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 condition for when to use this tool and names no alternative. With siblings like trawl_sync_pool and trawl_load_pool operating on the same pools, the agent has no routing signal for choosing a full reindex over an incremental sync.

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 carry the full behavioral burden. It sketches a three-step pipeline but does not disclose that the providers allowlist can cause the call to fail, whether context comes from a default pool, how many chunks are used by default, or what the response contains. Calling it a 'local LLM' run is also somewhat inconsistent with the schema's support for remote providers.

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 compact sentence, front-loaded with the core action and then the processing steps. It is efficient but so terse that important operational details are absent rather than merely compressed.

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 an agent-execution tool with five parameters, no output schema, and no annotations. The description should explain return behavior, provider-allowlist failure semantics, and the role of pool_name, but it leaves all of these to be inferred. An agent could invoke it, but it lacks enough context to predict outcomes or avoid configuration failures.

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 all five parameters, including defaults and the provider allowlist. The description does not add syntax or meaning beyond the schema's own field descriptions, which is the baseline for high-coverage schemas.

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 and resource: it runs a Trove agent, searches context, applies an agent prompt, and generates a response. That clearly distinguishes it from sibling tools like trawl_agents_list and trawl_agents_get, which inspect rather than execute agents. The phrase 'with local LLM' is slightly misleading because the schema's providers parameter accepts remote providers such as kimi, gemini, haiku, sonnet, and opus.

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 says what the tool does but gives no guidance on when to use it instead of trawl_agents_get, trawl_search, trawl_summarize, or other execution paths. It also omits any prerequisites, such as needing a valid agent_name or a pool_name for context retrieval.

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 of behavioral disclosure. It usefully states the hybrid retrieval mechanism and that it searches across all indexed documents, but it does not state read-only safety, result format, ranking behavior, or limits, even though 'search' strongly implies a non-destructive read.

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 definition is a single front-loaded sentence with no filler. The scope and retrieval mechanism are stated immediately, and every part of the sentence contributes 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 tool has six parameters and sits in a very crowded family of search-related siblings, with no annotations and no output schema. The one-sentence description is incomplete for routing and invocation because it does not explain when to choose this tool over alternatives or what result behavior to expect.

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 all six parameters, including mode, top_k, pool_name, max_tokens, and include_content. The description adds no parameter-specific meaning beyond what the schema provides, so the 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 names a specific verb and resource: search across all indexed documents. It also identifies the retrieval mechanism (hybrid BM25 + vector search). It does not explicitly distinguish itself from nearby siblings such as trawl_search_pool or trawl_search_multi, so it stops short of a 5.

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

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

The description provides no explicit guidance on when to use this tool versus the many other search tools, such as trawl_search_pool, trawl_search_multi, trawl_search_code, or trawl_search_entities. Any usage guidance is only implied by the word 'search' and the scope 'all indexed documents'.

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 behavioral burden and provides almost none. It does not state that this is a read-only/no-side-effect operation, nor does it describe result format, pagination, or any rate/permission 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?

A single front-loaded sentence with no wasted words. However, its brevity stems partly from under-specification rather than disciplined conciseness, keeping it from a top score.

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 five parameters and no annotations or output schema, the description is too thin. It omits the query parameter's role, top_k default/max, pool_name semantics, and return-value expectations, leaving significant gaps for correct invocation.

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

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

Schema description coverage is 100%, so the baseline is 3. The description mentions language and symbol type filters, which maps to two parameters, but adds no syntax, format, or default details beyond what the schema already documents for all five 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 states a specific verb ('Search') and resource ('code') and highlights two distinguishing capabilities (language and symbol type filters). It is clear what the tool does, but it never names or contrasts with sibling search tools like trawl_search, trawl_search_pool, or trawl_find_symbol, so an agent must infer 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?

No guidance is given on when to choose this tool over the many sibling search tools (trawl_search, trawl_search_pool, trawl_find_symbol, trawl_search_entities, etc.). The description implies usage only through the mention of filters, leaving the agent to guess selection criteria.

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 behavioral burden, but it discloses almost nothing. It does not state that this is a read-only operation, how results are ranked or paginated, what the default pool behavior is, or what the response contains.

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 wasted words. However, its brevity reflects under-specification rather than efficient communication, since it omits information an agent needs to select and invoke the tool correctly.

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 annotations, no output schema, four parameters, and dozens of sibling search tools, the one-sentence description is not complete enough. It leaves the agent unable to confidently distinguish this tool from related search tools or understand its operational 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 description coverage is 100%, so query, top_k, pool_name, and entity_type are already documented in the schema. The description adds no extra meaning about how these parameters interact or what entity_type values are valid beyond the schema's examples.

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 and resource: searching for entities in the knowledge graph. It is clear what the tool does, but it does not distinguish this from the many sibling search tools such as trawl_search, trawl_search_multi, trawl_search_relationships, or trawl_find_symbol.

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 on when to use this tool versus alternatives, no prerequisite or scope information, and no exclusions. The agent is left to infer usage from the name alone despite a crowded set of sibling search 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 provided, so the description carries the full behavioral burden. It does disclose that ranking uses reciprocal rank fusion and that omitting clients searches all available indices, which is useful behavioral context. But it does not state read-only safety, permissions, rate limits, or what the result set looks like.

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 core action and mechanism. There is no filler, and the default-client behavior is stated compactly.

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 five parameters, no annotations, and no output schema. The description does not explain what 'clients' are, how mode presets work, how per-client top_k results are merged, or what the token budget affects. For a multi-client search with several configurable knobs, the description is too sparse to fully orient an agent.

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 five parameters, including clients, mode, top_k, and max_tokens. The description only reiterates the clients default behavior ('Omit clients to search all'), which is already covered by the schema, adding no new semantic detail beyond it.

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 across multiple clients' and adds 'with reciprocal rank fusion', which gives a concrete mechanism. However, it does not explicitly distinguish itself from sibling search tools such as trawl_search, trawl_search_pool, or trawl_search_entities, leaving some ambiguity about which search endpoint to choose.

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 only guidance is 'Omit clients to search all', which is a parameter instruction rather than a when-to-use rule. The description provides no context on when this tool should be preferred over the many sibling search tools, nor any 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?

With no annotations, the description carries the full disclosure burden, yet it says nothing about return format, whether loading a pool is cached or costly, permissions, or failure behavior when the pool does not exist. Only the load-then-search sequencing is conveyed.

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 front-loaded sentence with no filler. It is efficient, though the brevity tips into under-specification rather than crisp precision.

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

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

For a tool with no annotations and no output schema, the description does not tell the agent what a 'pool' is, what results look like, or how this differs from the very similar siblings in the same namespace. The schema covers parameters, but the behavioral context is thin.

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 query, pool_name, and top_k are each documented in the input schema. The description adds no additional semantics (e.g., what a pool_name refers to or valid ranges for top_k), which is acceptable at baseline when the schema does the 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 action (search) and adds the distinguishing trait that it also loads the client, implying a combined load+search flow. However, it never names the pool/client concept clearly or distinguishes itself from siblings like trawl_search or trawl_load_pool, so the agent must infer the difference.

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 guidance on when to prefer this over trawl_search (with a pre-loaded pool) or the trawl_load_pool + trawl_search sequence. The phrase 'one-shot' hints at a convenience use case, but the agent is left to infer the tradeoffs.

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 of behavioral disclosure. It says nothing about whether the entity must already exist, whether the operation is read-only, how traversal cost scales with max_hops, or what the result contains — all important for a multi-hop graph traversal.

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 front-loaded sentence with zero redundant content. It is efficient, though its brevity comes at the cost of the missing detail noted elsewhere.

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 four parameters, no output schema, and no annotations, the description should explain traversal depth implications, how relationship_type narrows results, and what a pool scopes. None of that is present, leaving the agent to infer behavior from schema field names alone.

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 every parameter (entity, max_hops, pool_name, relationship_type) is already documented in the schema, including defaults and limits. The description adds no meaning beyond that, which is the baseline 3 case.

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 ('Search') and resource ('relationships between entities in the knowledge graph'), which is clearly distinct from entity search or graph statistics. It does not, however, distinguish itself from adjacent graph tools like trawl_build_graph, trawl_graph_stats, or trawl_graph_export beyond the word '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?

There is no guidance on when to use this versus trawl_search_entities or trawl_search_pool, and no prerequisite conditions (e.g., whether a graph must be built first). Usage is only implied by the verb.

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, yet it discloses nothing beyond the bare action: no read-only confirmation, no ranking/relevance behavior, no result volume defaults, no pagination. The only implicit signal is that "search" is a non-mutating operation.

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

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

A single front-loaded sentence with zero waste, but the brevity stems from omission rather than efficiency. It is adequately tight without being informative.

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, no annotations, and no output schema, the description should explain scoping (repo vs pool), what chunk_types filtering does to results, and roughly what comes back. None of that is present, so an agent cannot confidently choose this over sibling search tools.

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 all five parameters (query, top_k, pool_name, repo_name, chunk_types) are already documented in the schema. The description adds no meaning beyond that, which is the baseline 3 case.

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+resource ("search" + "within a specific repository"), which is more precise than a generic search. However, it does not distinguish this from the many near-identical siblings (trawl_search_pool, trawl_search_code, trawl_search_multi, trawl_search), leaving the agent to infer the scope difference from the name alone.

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 statement of when to use this versus trawl_search, trawl_search_pool, or trawl_search_code, which is a critical gap given roughly six overlapping search siblings. The word "specific" hints at scoping but no explicit selection condition 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 are provided, so the description carries the full burden. It discloses that an LLM is involved (implying cost/latency and non-determinism) but says nothing about expected latency, whether the synthesized output can drift from the source results, failure behavior, or whether the underlying search is read-only.

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 short sentence with the action front-loaded and no filler. It is efficient, though the brevity is the source of the ambiguity noted elsewhere rather than being purely virtuous.

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 4-parameter tool with no annotations and no output schema, the description should explain what a 'concise summary' looks like, whether original results are also returned, and how it relates to the plain search tools. None of that is present.

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 all four parameters (query, top_k, pool_name, providers) are already documented in the schema, including the provider allowlist failure semantics. The description adds no additional meaning beyond that, which is the baseline-3 case.

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?

It names a specific verb pair (search + return summaries) and the LLM mechanism, so the action is identifiable. But 'results' is undefined and the description never distinguishes it from the many search siblings (trawl_search, trawl_search_pool, trawl_search_multi), so an agent cannot confidently choose it over them.

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 statement of when to prefer this over plain retrieval tools, nor any exclusion. With over a dozen search-related siblings, the absence of any routing guidance is a real 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 are provided, so the description carries the full burden, and it does disclose real behavioral traits: the operation is incremental and state-dependent on a prior index. However, it omits that this mutates the pool index, what happens on a first-ever sync with no prior index, or any cost/failure 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 short clauses, front-loaded with the operative distinction (incremental vs. everything). 'Fast.' is mild marketing filler that earns little, but the rest is waste-free.

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?

It is a one-parameter, annotation-free tool with no output schema, so not much is needed, but the description leaves the relationship to trawl_reindex_pool, trawl_load_pool, and the ingest family unexplained, and says nothing about indexing side effects.

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% for the single pool_name parameter, so the schema already documents it. The description adds no naming, format, or lookup guidance for the pool identifier, which leaves it at the baseline.

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 semantics: incremental reindex that only processes new/modified files. The scope contrast (incremental vs. full) is clear, but the description never names trawl_reindex_pool, the sibling it most needs to be distinguished from, so the agent must infer the difference from the tool names alone.

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?

'Only process new/modified files since last index' implies this is the cheap default path versus a full rebuild, and 'Fast.' reinforces that, but there is no explicit when-to-use/when-not statement and no pointer to trawl_reindex_pool for the full case.

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 for what is clearly a mutating, network-touching operation. It hints at external side effects ('pull latest from git repos') but never says whether it overwrites local state, whether it is idempotent, whether credentials are required, how long it may run, or what happens to sources that fail to pull. For a write/sync tool with zero annotation coverage this is a substantial 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?

A single short sentence with the operation front-loaded and no padding. The trailing 'etc.' weakens it, and the 'client' phrasing is a concision-induced defect, but structurally it is efficient and readable.

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

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

A mutating sync tool with no annotations, no output schema, an underspecified required parameter, and an undifferentiated sync sibling must explain far more than one sentence. An agent cannot tell what gets synced, whether it is safe to run repeatedly, or what it will get back.

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?

Coverage is nominally 100%, but the schema's own text is just 'Pool name' — content-free. The description's only parameter reference is 'for a client', which introduces a client/pool vocabulary mismatch rather than resolving it. The description therefore adds ambiguity instead of meaning.

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 (sync) and resource (all sources), and the parenthetical clarifies that this means pulling from git repos and similar origins. However, it calls the subject 'a client' while the schema requires 'pool_name', so the agent cannot be certain whether the client/pool identity is the same thing. Sibling trawl_sync_pool is not distinguished from this tool at all.

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 statement of when to use this versus trawl_sync_pool, trawl_list_sources, or trawl_reindex_pool — all of which plausibly touch the same sources. No prerequisites (connected GitHub via trawl_connect_github, pool loaded via trawl_load_pool) 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?

No annotations are provided, so the description carries the full burden. It does not disclose whether creation is idempotent, what happens on a duplicate name, whether depends_on references are validated or must point to earlier steps, or what identifier is returned. For a write operation with zero annotation coverage this is a substantial 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?

A single front-loaded sentence with no filler. It is efficient, though its brevity borders on under-specification given the tool is a mutation with no annotations.

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 create/mutation tool with three parameters, no annotations, and no output schema, the description should cover side effects, uniqueness behavior, return value, and pool scoping. None of these are present, leaving the agent to guess at critical 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 description coverage is 100%, so baseline is 3. The description's mention of 'named steps and dependency ordering' only echoes the schema's steps/depends_on documentation and adds no format, constraint, or validation detail beyond it.

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 (Create) and resource (workflow) plus the defining content: named steps with dependency ordering. An agent can tell it apart from trawl_workflow_update or trawl_workflow_list by verb alone, but the description never explicitly names those siblings or scopes itself against them.

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 on when to use this versus trawl_workflow_update (modify existing), trawl_workflow_list (discover existing), or trawl_workflow_status. No prerequisites are mentioned, such as whether a pool must be loaded first via trawl_load_pool or whether the workflow name must be unique.

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. "List" implies a safe read, but nothing is said about result size, pagination, ordering, or whether the set is scoped to a project/pool — real concerns for an unbounded "all workflows" call.

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 front-loaded sentence with no filler. Nothing could be removed without losing meaning.

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 two-parameter list tool with no output schema, the core is covered, but the agent is left guessing about scope (pool_name's effect) and result volume. Minimum viable rather than complete.

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

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

Schema description coverage is 100%, so both parameters are already documented, including the valid status values. The description adds only a passing mention of the status filter and never mentions pool_name, so it does not exceed 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?

States a specific verb and resource ("List all workflows") plus the optional filter, so the agent knows exactly what it returns. It does not distinguish itself from sibling reads such as trawl_workflow_status or trawl_workflow_create, leaving differentiation 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?

No statement of when to use this over trawl_workflow_status (single workflow lookup) or trawl_list_pools. The word "optionally" hints at filtering but never tells the agent when filtering matters or what happens without 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 are provided, so the description carries the full disclosure burden. 'Get' implies a read, but the description does not state whether it is read-only, whether it requires authentication or specific pool permissions, or what happens with invalid workflow IDs.

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

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

The description is a single, front-loaded sentence with no filler. It states the core action and the information returned, earning every word.

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 tool with fully documented input parameters and no output schema, the description is minimally adequate. It says it returns status and step progress, but it does not clarify status values, output shape, or whether progress includes step-level details.

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

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

Schema description coverage is 100%, so both parameters and their meanings are documented in the schema. The description adds no parameter-level detail beyond what the input schema already provides, which is acceptable at the baseline for high 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 states a specific verb and resource: 'Get workflow status and step progress.' An agent can identify the tool as a read operation for a particular workflow, though it does not explicitly distinguish this from siblings like trawl_workflow_list or trawl_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?

Usage is implied by the tool name and the phrasing: check an existing workflow's status and step progress. However, there is no explicit guidance on when to use this instead of trawl_workflow_list, trawl_workflow_update, or other status-related 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 provided, so the description bears the full disclosure burden, and it discloses almost nothing. It does not say whether status transitions are validated, whether updates are idempotent, whether the step must be in a particular state, or what happens to the optional result text — all critical 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?

A single front-loaded sentence with zero padding. It is efficient, though its brevity reflects under-specification rather than disciplined editing, which is penalized elsewhere.

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 five-parameter mutation tool with no annotations and no output schema, one sentence is far too thin. An agent cannot tell what a successful update returns, whether the workflow's own status changes, or how failures are surfaced.

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 each of the five parameters already has an inline description, including the enumerated status values. The description adds no meaning beyond the schema, which meets the baseline of 3 when the schema does the heavy lifting.

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 and resource ('Update a workflow step's status'), which is clearly narrower than trawl_workflow_status or trawl_workflow_create. However, it under-describes the tool's actual scope, since the schema also accepts result text and pool_name, so the stated purpose covers only part of what it does.

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 call this instead of trawl_workflow_status or trawl_workflow_create, and no mention of prerequisites such as a step already existing in a running workflow. The agent must infer its place in the workflow lifecycle entirely from the name.

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