stigmergy

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 the tool returns citations, which is a useful behavioral trait. However, it does not mention any access limitations, error conditions, or whether it is a read-only operation. Given the simplicity, a 3 is appropriate.

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

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

The description is a single, concise sentence that conveys the core purpose without any fluff. It is front-loaded and easy to parse.

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

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

Given the output schema exists and there is only one parameter, the description is fairly complete. It specifies the scope (ACL-visible knowledge) and the output characteristic (citations). It does not need to explain return format since the output schema handles that. A minor gap is the lack of any mention of usage context, but overall adequate.

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

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

The schema has zero description coverage, so the description must explain the 'question' parameter. The description implies the question is the input but does not add any details about format, length, or constraints. It adds minimal value beyond the parameter name.

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 answers from ACL-visible team knowledge and includes citations. It is specific about the resource (team knowledge) and the output (answer with citations). However, it does not explicitly differentiate from sibling tools like search_brain, so it lacks a clear distinction.

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

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

The description provides no guidance on when to use this tool versus alternatives. It does not mention any exclusions or conditions for using search_brain or read_page. The implied use case (asking a question) is present but not explicitly framed against siblings.

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 does reveal that the operation is queued and authorized, but it does not state whether the deletion is permanent, reversible, requires approval, or how the result of the queued operation can be observed. For a destructive tool, this is a significant transparency gap.

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

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

The description is a single sentence with no filler, and the core action is front-loaded. It is concise and easy to parse quickly, though it sacrifices useful semantic detail for brevity.

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?

Even though an output schema exists, this is a destructive, queued mutation with no annotations and two required parameters. The description leaves critical contextual unknowns: what 'authorized' means, what path formats are valid, why the 'why' parameter is required, and what happens after queueing. This is not complete enough for safe and 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?

The schema has no property descriptions and schema description coverage is 0%, so the description must compensate. It hints that 'paths' refer to pages or sources, but it never explains the 'why' parameter, its purpose, format, or required content. The description adds only minimal meaning beyond the raw schema field names.

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, 'Queue', and names the resource, 'page or source deletion', which tells an agent what the tool does. It is distinguishable from sibling tools like read_page, search_brain, and brain_submit. However, the qualifiers 'authorized' and 'explicit' are ambiguous and slightly obscure the exact nature of the deletion.

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

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

The description gives no guidance on when to use this tool versus alternatives. It does not mention exclusions, prerequisites, or conditions that would lead an agent to choose brain_delete instead of read_page or brain_submit. The only usage signal is the word 'deletion', which is implicit rather than explicit.

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

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

No annotations are present, so the description must carry the behavioral burden. 'List' implies a read-only operation, and the status scope is stated, but the description does not explicitly confirm no side effects, nor does it explain how the status filter behaves when empty or how the output is ordered/paginated. The output schema covers the return shape, but behavioral details remain 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 that front-loads the action and immediately specifies the status scope. Every word earns its place; there is no redundant phrasing or 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?

The tool is simple and has an output schema, so return values are covered. But with no annotations, no parameter descriptions, and no usage guidance, the description leaves gaps around default behavior and when to choose this tool over siblings. Adequate, but not fully complete for an agent operating autonomously.

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

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

With 0% schema description coverage, the description must compensate. It does add meaning to the status parameter by listing the four possible statuses, which is helpful. However, it says nothing about the limit parameter or its default, nor about how an empty status is interpreted. The compensation is partial at best.

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 ('List') with a clear resource ('submissions') and enumerates the exact statuses covered (queued, processing, landed, failed). This clearly distinguishes it from sibling tools like brain_submit or brain_delete, which imply write operations.

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 status enumeration implies a monitoring use-case, but there is no explicit guidance on when to use this tool versus alternatives like search_brain or list_entities. No when-not-to-use or exclusion conditions are stated, leaving the choice to inference.

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

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

With no annotations, the description carries the full behavioral burden. It does disclose one genuine gate: an explicit resolution_of target is subject to the cloud writer's evidence and ACL checks. But it does not describe the write effect beyond 'submit'—whether it creates a new entry, updates existing content, or how rejection/failure surfaces—so the transparency is partial.

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

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

Two sentences with no filler: the core action and payload constraint are front-loaded, and the second sentence earns its place by warning about resolution_of gating. Every sentence contributes essential information.

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

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

The description resolves the hardest ambiguities: the exactly-one payload rule and the special gated behavior of resolution_of. An output schema exists, so return-value documentation is not required. It does not spell out the three remaining metadata parameters, but their names are conventional and lower-risk, making the tool largely usable as written.

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

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

Schema description coverage is 0%, so the description is the only source of parameter meaning. It usefully clarifies that text/path/url form a mutually exclusive payload set and that resolution_of has validation/ACL implications. However, title, audience, and occurred_at are left entirely to name-based inference, leaving a gap in a 7-parameter optional 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 first sentence names a concrete action ('Submit'), a precise payload restriction ('exactly one text value, local file path, or URL'), and a destination ('team wiki'), which clearly separates it from the read/search/delete siblings in the tool list. The second sentence adds a meaningful caveat rather than blurring the purpose.

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

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

The description implies a write/submit context through the verb and destination, and it explicitly states the exactly-one input rule. However, it gives no direct when-to-use guidance or alternatives such as 'use search_brain/read_page for retrieval.' The choice among brain_submit and its siblings is left mostly to inference.

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

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

Since no annotations are present, the description carries the full burden. It adds useful behavioral context by stating the output is bounded, ACL-visible, and includes cited relationship evidence. However, it does not disclose whether the operation is read-only, error semantics, or any permission requirements beyond the ACL mention.

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, focused sentence of about 10 words. It front-loads the most distinctive attributes and avoids filler, making it efficient and easy to scan.

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 an output schema, so return shape may be covered elsewhere, but the description does not explain the required input parameter at all. With no usage guidance and zero schema description coverage, an agent lacks enough information to construct a correct call confidently.

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

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

Schema description coverage is 0%, so the description must compensate for the single required 'entity' parameter. It does not explain what form the entity value should take (ID, name, slug), any validation rules, or examples. The description adds no meaning beyond the parameter name itself.

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

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

The description names a specific action ('Return') and resource ('entity dossier') with distinctive attributes ('bounded, ACL-visible, cited relationship evidence'). It is clear enough to separate from siblings like list_entities or read_page, though it does not explicitly reference alternatives.

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 siblings such as search_brain, read_page, or list_entities. The description implies it is for a single entity dossier, but no explicit context, prerequisites, or exclusions are provided.

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

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

With no annotations, the description carries the full burden of behavioral disclosure. It does convey that the operation is a read-only listing (via 'List') and that results are scoped to the reader's visibility, which is useful. However, it does not disclose potential limitations (e.g., pagination, ordering, whether identities are returned as IDs or full objects, or error behavior). The description is minimally transparent but not misleading.

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, tightly worded sentence with no filler words or redundant information. It front-loads the action and resource immediately. Every word contributes to understanding the tool's purpose and scope, making it a model of 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?

For a tool with no parameters and an existing output schema, the description is largely sufficient. It specifies what the tool does and the permission context ('visible to the current reader'). The only notable gap is the absence of usage guidance relative to sibling tools, but this is more of a usage-guidelines concern. Given the simplicity of the tool, the description is adequately complete without needing to detail return structures or 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?

The tool has zero parameters, and the schema coverage is 100% because the properties object is empty. Per calibration, a baseline of 4 applies when params are absent. The description does not need to explain parameters, and it doesn't introduce any ambiguity about parameter usage. It adds no parameter semantics because there are none to add, leaving the baseline score 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 specific action (List), the resource (entity identities), and the scope (visible to the current reader). This distinguishes it from siblings like describe_entity, which would provide detailed information about a single entity, and search_brain, which implies a search operation. The verb and object are unambiguous and not tautological.

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 alternatives. While the purpose implies it should be used for enumerating accessible entities, there is no mention of exclusions or scenarios where a sibling tool would be more appropriate. The agent is left to infer usage solely from the tool's name and one-line 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 behavioral burden. It does add useful context with 'ACL-visible,' indicating access-control filtering applies. It does not disclose behaviors like not-found handling or permission requirements, but for a simple read operation this is a reasonable minimal disclosure.

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

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

The description is a single, compact sentence with no filler. Every word earns its place, and the core action and resource are front-loaded.

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

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

With an output schema present and only one required parameter, the description does not need to explain return values extensively. Still, the lack of path format details and the absence of any sibling guidance leave meaningful gaps for an agent deciding how and when to call this tool.

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

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

Schema description coverage is 0%, and the description does not explain the meaning or expected format of the 'path' parameter. The phrase 'wiki page' only weakly suggests that path refers to a page identifier, leaving the agent to infer the actual path semantics.

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

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

The description clearly identifies the action ('Read') and the resource ('wiki page'), and the qualifier 'one ACL-visible' narrows it to a single page. It is distinct enough from siblings like search_brain and list_entities, though it does not explicitly name or contrast those alternatives.

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

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

The description implies the tool should be used when an agent needs to read a single ACL-visible wiki page, and it hints at a boundary via 'one.' However, it provides no explicit guidance about when not to use it or which sibling tool should be preferred for searching or 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?

With no annotations, the description carries the behavioral burden. It discloses two useful traits: ACL-scoped visibility and hybrid ranking. However, it does not address result limits, pagination, or other operational details, so transparency is only moderate.

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. It communicates the action, scope, and a key behavioral trait 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?

Despite having an output schema, the description is too sparse for a tool with three parameters and no annotations. It omits parameter semantics, filter expectations, and any relationship to sibling tools, so an agent would need to guess at how to construct valid calls.

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

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

Schema description coverage is 0%, so the description must compensate, but it only implicitly supports the query parameter via the verb 'Search'. Filters and max_results are not explained, and the description adds no meaning beyond their names and 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?

The description uses a specific verb ('Search') and identifies a distinct resource ('ACL-visible team knowledge'), making the core purpose clear. It does not explicitly name any sibling tool it is not, so it misses the top score for sibling 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?

The description gives no guidance on when to use search_brain versus siblings such as ask, list_entities, or describe_entity. There is no exclusions or alternatives, leaving the agent to infer the appropriate context.

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