PersonalKnowHow

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

Beyond the readOnlyHint annotation, the description discloses that results are complete, exact, have no relevance cutoff, no count cap, and are deterministically sorted by label. It also guarantees repeated calls return the same list in the same order, which is valuable context for multi-step agent workflows.

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 efficiently front-load the core behavior, then provide usage guidance and ordering guarantees. Every sentence adds unique information with no filler or 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 single-parameter, read-only listing tool with complete enum documentation, the description covers completeness, use cases, ordering, and determinism. The lack of an output schema is acceptable because the return shape—an exhaustive list of entries of the specified type—is clear from the description.

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 already fully documents the single 'type' parameter with an enum and the description 'Exact entry type to list in full', so schema coverage is 100%. The description adds no parameter-level detail beyond referring to 'one type' and 'same type', meeting the baseline but not exceeding 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 uses a specific verb ('Returns') and a precise resource ('complete, exact set of entries for one type'), and explicitly contrasts with query_knowhow's relevance-based behavior. Its function is unmistakable and well-differentiated from the primary sibling.

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 explicitly directs agents to use this tool instead of query_knowhow whenever an exhaustive or countable answer is needed, with concrete examples ('list all my certifications', 'how many courses have I completed'). The deterministic ordering statement further clarifies when repeated reliable results matter.

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

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

Annotations only declare readOnlyHint=true, but the description adds substantial behavior: semantic ranking, a 10-result cap, non-exhaustive results, evidence-only dataset content, source fields, and the risk of topically-adjacent wrong matches. This goes well beyond what annotations provide and contains no contradiction.

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

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

The description is long but purpose-first: it front-loads the core action, then gives boundaries, evidence handling, and failure modes. Each sentence earns its place, though there is slight redundancy around 'real evidence' and the caveats could be tightened without losing value.

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

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

With no output schema, the description still covers result caps, result fields (source_url/captured_at/provider/source_note), false-positive behavior, and alternative tool routing. An agent has everything needed to call it correctly and interpret results safely.

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 already documents the single topic parameter with examples, so the baseline is 3. The description adds meaning by clarifying that topic matching is semantic rather than literal, ranked by relevance, and may return adjacent-but-wrong entries — important context for interpreting results.

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 opens with a specific verb ('Search ... using semantic search') and names the exact resource ('person's real, grounded skills/experience graph'). It also distinguishes itself from siblings by stating it is capped at 10 results and only returns evidence-backed entries.

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 explicitly tells the agent when NOT to use this tool: for exhaustive 'list every X'/'how many X' questions, use list_by_type; for relationship questions, use related_entries. It also instructs treating off-topic semantic matches as unmatched, providing clear decision rules for ambiguous results.

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

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

Annotations already declare readOnlyHint=true, and the description adds substantial behavioral detail beyond that: only two relationship types exist, results are capped at 15 and sorted by label, the true total count is shown separately, and the tool is not a relevance/similarity judgment. These caveats help an agent interpret results correctly. No contradiction with annotations.

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 longer than average but every sentence carries meaningful guidance: relationship semantics, limitations, truncation behavior, and usage context. It front-loads the core function, though some examples could be trimmed without losing value.

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's moderate complexity, one parameter, no output schema, and available sibling context, the description fully covers what an agent needs: input provenance, output shape and limits, caveats about semantic relevance, and when to use an alternative. Nothing critical is missing.

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

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

Schema coverage is 100% and the schema already documents id as 'an entry id from a prior query_knowhow or list_by_type result.' The description reinforces this provenance and clarifies what kind of id is expected, adding a small amount of value beyond the schema without needing to repeat format details.

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: 'returns other entries that share at least one tag or the same content provider.' It explicitly distinguishes itself from query_knowhow's similarity search and names the prior tools that produce the input id, so an agent can clearly understand what this tool 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?

Provides explicit when-to-use guidance ('what else is connected to X', 'what did they do that relates to this...'), explicitly contrasts with query_knowhow's similarity search, and gives an actionable alternative ('call list_by_type on that type if you need the full set') when results are truncated. This is exemplary routing guidance.

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

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

Beyond the readOnlyHint annotation, the description discloses exact-match semantics, uncapped results, grouping by type with real counts, sorting behavior by captured_at, undated_count handling, and the found:false response for unmatched tags. This is rich behavioral context that annotations alone do not provide.

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?

Every sentence delivers essential information: main behavior, sibling contrasts, usage guidance, exact-match caveats, and sorting/undated_count semantics. The description is dense but focused, front-loading the core behavior before differentiation and edge cases.

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

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

With no output schema, the description compensates by explaining return semantics: grouped entries, counts, sorting, undated_count, and found:false. It covers the main usage scenarios and edge cases effectively, leaving no critical gap for an agent to call it 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 description coverage is 100%, so baseline is 3. The description adds extra meaning by emphasizing that the tag must be an exact string from a prior result's tags array and explicitly warns 'this is NOT semantic search', reinforcing correct parameter usage 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 action and resource: 'returns EVERY entry with that tag, uncapped, grouped by type with a real count per type.' It clearly distinguishes itself from siblings by naming related_entries and query_knowhow and explaining their differing behavior.

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?

Explicit when-to-use guidance is provided: 'the right tool for "how many X have I completed/done" or "do I have any real evidence for X at all".' It also names alternatives and their limitations, and tells the agent to try query_knowhow if an exact tag returns found:false.

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