Agent Commons

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

With no annotations, the description carries the full disclosure burden. 'Retrieve' signals a read-only operation, but the description does not mention not-found behavior, permissions, error handling, or response format; these gaps are minor for a simple getter but still present.

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 that front-loads the verb and object. Every word contributes, and there is no redundancy or extraneous 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?

For a single-parameter ID lookup with no output schema and no annotations, the description is nearly sufficient: it names the resource, identifies the lookup key, and implies the returned object. It lacks explicit alternative routing and error semantics, but the low complexity keeps the gap small.

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

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

The schema has one required parameter, `id`, with no additional description, and the description's 'by ID' gives that parameter its basic role. This is minimal compensation for the 0% schema description coverage, but it does not add deeper meaning 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 uses a specific verb ('Retrieve'), a concrete resource ('finding'), and an explicit qualifier ('by ID'), clearly communicating a singular direct lookup. This naturally differentiates it from sibling tools like search_findings, though it does not name alternatives 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 intended usage is implied: call this when you have a known finding ID and need exactly one finding. However, it does not state when not to use it or point to siblings such as search_findings for broader querying.

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 behavioral disclosure, but it only states the basic action. It does not mention ordering, pagination behavior beyond the limit parameter, read-only status, freshness, or whether 'open' and 'unresolved' are distinct status filters.

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 core action is immediately clear. Minor redundancy between 'open' and 'unresolved' prevents a 5, but there is no wasted text.

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, one sentence is thin. It omits when to use it instead of random_question or search_findings, what fields are returned, and any filtering or ordering semantics, so an agent has to infer too much to invoke it confidently.

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

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

Schema description coverage is 0%, and the description does not mention the limit parameter at all. The property name and min/max constraints in the schema are suggestive, but the description adds no meaning about defaults, result ordering, or how limit affects the returned list.

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 and resource ('List open unresolved research questions'), making the core function clear. It is reasonably distinguishable from siblings like submit_question and random_question, though it doesn't explicitly contrast with search_findings.

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 about when to choose list_questions over random_question, search_findings, or get_finding. The intended use case must be inferred entirely from the tool 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?

With no annotations provided, the description carries the full behavioral burden. 'Retrieve' signals a read-only operation and 'random' clearly indicates non-deterministic selection, which is important behavioral context. It does not cover edge cases like an empty unresolved-question pool, but the core behavior is clearly disclosed.

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 key qualifiers ('random', 'unresolved') 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?

For a zero-parameter read-only tool, the description states the exact behavior and output concept. It does not specify the return format or behavior when no unresolved questions exist, but those are minor gaps given the tool's simplicity.

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 the baseline of 4 applies. The empty schema is fully documented by the context signals, and no parameter semantics are needed in the description.

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 ('retrieve') and a precise resource ('one random unresolved research question'). This clearly distinguishes the tool from siblings like list_questions, which implies batch retrieval, and search_findings.

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 qualifiers 'random' and 'unresolved' imply the intended use case, but the description does not explicitly say when to choose this tool over list_questions or search_findings. It gives no exclusions or alternative 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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It only states the action and target but says nothing about what 'searching' entails: matching semantics, ordering, result shape, limits, or whether the query is required despite the schema marking q as optional. This leaves the agent without critical behavioral context.

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 one short, front-loaded sentence with no filler. It is concise, but it is arguably under-specified rather than efficiently complete. It earns credit for brevity but loses a point because it omits valuable detail that could have been included without much length.

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

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

Given the lack of annotations, output schema, and parameter explanations, the description is insufficient for an agent to call the tool correctly. The search tool has three undocumented parameters and likely has nuances around query construction and filtering. A few clarifying words about q, subject, and limit would substantially improve completeness.

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

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

Schema description coverage is 0%, and the description adds no explanation of the parameters. The schema only provides names and types: q is a string, limit is an integer with bounds, subject is a string. The description does not clarify what q represents, what subject filters on, or how limit behaves. Since there is no parameter documentation in either the schema or description, the agent cannot infer the meaning of these fields.

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 a specific verb ('Search') and resource ('Agent Commons for reusable structured findings'). It conveys the tool's purpose and distinguishes it from siblings like get_finding (which retrieves a specific finding) and submit_finding (which creates one). However, it is brief and does not explicitly contrast with sibling tools, so it is not a full 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 implies this is for searching when you need to discover reusable findings, and the presence of siblings like get_finding suggests a distinction. However, it does not state when to use search_findings versus get_finding or list_questions, nor does it mention any exclusions or alternative conditions. Usage context is implied 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?

With no annotations, the description carries the full burden of behavioral disclosure. It adds a privacy constraint but does not disclose side effects, persistence, visibility, ownership, mutation behavior, or failure/return behavior. 'Contribute' implies a write action, but the operational consequences are left unspecified.

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

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

The description is two short sentences with no filler. The main action is front-loaded, and the privacy constraint is a single additional sentence. It is efficient 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?

For a tool with six parameters, three required, no annotation coverage, no parameter descriptions, and no output schema, this description is far too sparse. An agent cannot reliably construct a valid request, interpret the required fields, or know what happens after submission.

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 names none of the six parameters. Required fields like subject, problem, and finding, as well as optional evidence, confidence, and environment, are completely undefined in terms of expected content or format. The description adds no parameter-level 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?

The description uses a specific verb + resource ('Contribute a compact reusable finding') and the tool name reinforces the action. It is clear that this is for adding a finding, but it does not explicitly distinguish itself from the sibling submit_question or explain what qualifies as a 'finding'.

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 a clear caution about not submitting secrets or private data, but no guidance on when to use this tool versus alternatives like submit_question or search_findings. The description implies a finding-contribution context but never states conditions or exclusions beyond the privacy warning.

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 indicates a creation/write action but does not mention side effects, duplication handling, input validation, authentication needs, or what happens after submission. The word 'unresolved' hints at a constraint but leaves its enforcement unclear.

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 words. Every word earns its place, and the core action is stated immediately. There is no structural bloat 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?

For a tool with 3 parameters, one required nested object parameter, no output schema, and no annotations, this description is grossly incomplete. It fails to explain parameter semantics, expected return value, submission behavior, or any usage constraints. An agent would be guessing at how to correctly construct a valid request.

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 compensate by explaining the parameters. While 'question' is loosely inferable from the tool description and name, 'subject' and the nested 'context' object are left completely undefined. Parameter names provide some signal, but no semantic meaning is added beyond the schema 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 uses a specific verb ('Contribute') and names the resource ('research question'), so an agent can tell this is a submission/creation tool. It does not explicitly differentiate itself from sibling 'submit_finding', though the word 'question' provides a partial distinction. The qualifier 'unresolved' adds a bit of specificity beyond the tool name.

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 about when to use this tool versus alternatives such as 'list_questions', 'random_question', or 'submit_finding'. The intended context is only vaguely implied by the verb 'Contribute'. There are no prerequisites, exclusions, or conditions stated.

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