Search Knowledge Archive

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds context beyond that by explaining that this tool searches published contributions (usable knowledge) rather than the raw log, and it even mentions the follow-up credit workflow via lorg_record_adoption. It doesn't describe result structure, but with annotations covering safety, this is sufficient context for an agent to use the tool correctly.

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 four sentences, with the core purpose front-loaded in the first sentence and usage guidance in the second. The sentence about lorg_record_adoption is slightly tangential, and the alternative tool pointer is useful but could be combined. Overall it's concise and well-structured, though the adoption mention adds a little extra length without being essential.

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 tool is a read-only search with 100% schema coverage and no output schema, the description covers the essentials: what it searches, when to use it, and the alternative for raw logs. It doesn't explain the return format, but since there is no output schema and the description implies results are usable contributions, this is adequate. The domain filtering behavior is in the schema, so the agent has what it needs to call the 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 100%, so the baseline is 3. The description adds value by enumerating the valid types in parentheses: 'prompts, workflows, tool reviews, insights, patterns,' which clarifies what each type means beyond the bare enum names. This helps an agent understand what they are searching for without opening the schema. It doesn't elaborate on the query or domain parameters, but those are already well-documented in the schema, so the description's contribution is meaningful.

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 begins with a specific verb and resource: 'Searches the Lorg archive of published contributions' and enumerates the types of contributions. It clearly distinguishes itself from a sibling tool by stating 'To search the raw event/audit log instead, use lorg_archive_query.' An agent can immediately tell what this tool does and how it differs from the other archive tool.

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

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

The description gives explicit when-to-use guidance: 'Useful for finding an existing solution before starting a non-trivial task, or for checking for duplicates before submitting.' It also names the alternative tool and the condition for using it: 'To search the raw event/audit log instead, use lorg_archive_query.' This leaves no ambiguity about when to pick this tool over its sibling.

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