uNotes

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint false, and openWorldHint false, so the safety profile is fully covered. The description adds a list of returned metadata fields, which is return-content rather than behavioral disclosure; it omits auth, rate-limit, and failure-mode 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?

Two tightly written sentences: the first front-loads purpose and return fields, the second is a routing pointer. Every element earns its place, with no 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?

No output schema exists, so enumerating the returned metadata fields is necessary and is present. With annotations covering the safety profile, an agent has enough to call the tool 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 single documentId parameter is fully documented. The description says 'by ID' and lists fields, but adds no syntax or format details 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 (Get), resource (metadata of a single uNotes document), and scope (by ID). It explicitly distinguishes itself from get_document_content by directing content reads elsewhere, so an agent can tell them apart without opening schemas.

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?

Names the alternative tool get_document_content and the condition that selects it ('to read the actual text'), effectively routing the agent. No further when-not guidance is necessary given the sibling set.

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 readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds only that the full text is returned; it says nothing about size limits, truncation, pagination, or behavior when none/multiple IDs are supplied. Useful but thin on top of the 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?

Two sentences, front-loaded with the action and scope, with no redundant restatement of the title. The second sentence earns its place as routing guidance, though it is slightly generic.

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 three optional, mutually ambiguous ID parameters, the description should clarify how to select the identifier and what the returned content looks like. It covers the happy path but leaves the calling convention underspecified.

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 three ID parameters are already documented. The description echoes the same three material types but never resolves the key ambiguity: all three parameters are optional, and an agent is not told whether to supply exactly one, whether multiple are allowed, or how conflicts are resolved.

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 ('Get the full text content') and enumerates the three material types it covers, which distinguishes it implicitly from the metadata-oriented sibling get_document. It stops short of naming that sibling or explicitly contrasting content vs. metadata, so the differentiation is inferable rather than stated.

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?

Gives a clear when-to-use condition: read the actual content to answer questions about a material. It does not name alternatives (e.g., get_document for metadata, search_library for discovery) or state when this tool is the wrong choice, so routing to siblings is left 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?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so safety is covered structurally. The description adds genuinely useful semantics beyond that: it identifies the resource as the authenticated user's own data and explains that a null limit means unlimited, which is not derivable from the 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?

One dense but well-formed sentence front-loads the resource and scope, with a short trailing sentence carrying the only non-obvious semantic (null = unlimited). 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?

There is no output schema, so the description carries the burden of describing the return shape; it does so adequately by naming plan tier and per-quota usage, plus the null-limit convention. It stops short of specifying the response structure or whether usage is returned as absolute counts or percentages, leaving a small 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?

Schema description coverage is 100% and the single enum parameter is fully documented in the schema, including the omit-for-all behavior. The description's enumeration of quota areas loosely mirrors the enum values but adds no syntax or format detail, 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?

Names a specific verb (get) and resource (quota status) and enumerates the exact quota dimensions returned, so an agent can distinguish it instantly from siblings like get_document or list_my_quizzes.

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 usage context (checking the authenticated user's plan tier and consumption), but it never states when to call this versus alternatives or any prerequisite conditions. No sibling overlap exists to disambiguate, so the omission is mild but present.

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, idempotentHint and destructiveHint=false, so safety is covered. The description adds genuinely non-derivable behavior: the day boundary is UTC and milestone badges are awarded at 7/30/100/365 days, which an agent cannot infer from the schema.

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 resource and then enumerates the return payload; every clause carries information and nothing is repeated from annotations or schema.

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 usefully enumerates the returned fields (current streak, longest, studied-today, badges), which is exactly what's needed. Minor gap: it doesn't explain how streaks break (e.g. missing a day) or whether zero-state is returned.

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?

Zero parameters, so there is nothing for the description to disambiguate; baseline 4 applies. The description correctly adds no spurious parameter guidance.

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?

Specific verb+resource ('Get the authenticated user's daily study streak') with the scope narrowed to the caller's own data, which separates it from sibling list_* and get_document 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?

Usage is only implied — the description makes clear this returns the caller's own streak, but it never states when to reach for it over siblings or any precondition (e.g. no authentication requirement stated). For a zero-argument self-scoped getter this is adequate but thin.

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 readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds the result ordering ('newest first') and the user-scoping, but says nothing about pagination behavior or how the set list is shaped beyond that.

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 compact sentences, front-loaded with the core action and scope, followed by usage routing and the library-search exclusion. Every sentence carries information with 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 read-only list tool with no output schema, the description covers scope, ordering, filtering and routing. The only real gap is pagination guidance for skip/limit, which matters given the 12 default and 30 cap.

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 only 33%: 'query' is documented in the schema, while 'skip' and 'limit' are not. The description restates the query filter semantics (title, subject, course code) but does not compensate for the undocumented pagination parameters or explain the 30-item maximum.

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 (authenticated user's own flashcard sets) with a scope qualifier (on uNotes, newest first). It is clearly separable from siblings list_my_quizzes and search_library, which cover different resource types.

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 says to use it for any question about the user's flashcards and adds an exclusion ('The document library search does not cover them'), which routes the agent away from search_library. It does not, however, contrast against list_my_quizzes, the closest sibling.

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 cover the safety profile (readOnly, idempotent, non-destructive). Description adds ordering behavior ('newest first') and ownership scoping ('own quizzes'), which is useful beyond annotations. However, it doesn't mention default limit/pagination behavior, which matters for a list 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 sentences, front-loaded with the core purpose. The example query and sibling-differentiation earn their place. Slightly dense but no wasted phrasing.

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 list tool with no output schema, the description covers purpose, routing, ownership scope, ordering, and query semantics. Missing pagination guidance (skip/limit defaults) is a minor gap against a fairly complete picture.

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 only 33% — only 'query' is documented in the schema. Description compensates by explaining query accepts a course code or quiz title, matching the schema's stated purpose. However, skip and limit are undocumented in both schema and description. Baseline 3 given partial compensation.

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?

Specific verb (List) + scoped resource (authenticated user's own quizzes) with clarifying parenthetical about what 'quizzes' means (courses where user uploaded docs). Explicitly distinguishes from siblings: 'the document library search does not cover them,' separating it from search_library.

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 (any question about the user's quizzes) with a concrete example query. Names the alternative (document library search / search_library) and states why it doesn't apply. Both routing and example 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, openWorldHint=false, and destructiveHint=false, so the safety profile is covered. The description adds only the intended use case, saying nothing about result shape, pagination, or how limit interacts with matching results.

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 waste, with the core action front-loaded and the usage condition following. Nothing is padded, though it is generic enough that it could carry one more differentiating detail at no cost.

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 4-optional-parameter read tool with no output schema, the description covers the basic purpose but omits any mention of return content, result limits, or the schoolId/type interplay. Adequate but with clear gaps given no output schema exists to fill them.

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 75%, with 'type', 'query', and 'schoolId' already documented inline (including the enum values and the 'omit when unknown' note). The description adds no syntax or format detail 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: 'Search for schools and courses on uNotes.' That distinguishes it from the document/flashcard siblings, though it does not explicitly name an alternative search tool it might be confused with.

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?

Gives a concrete trigger condition: use when the student needs to find a school or course for uploading a document or creating flashcards. Clear context, but no explicit exclusions or named alternatives for 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?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds genuinely new behavioral context: the library is public, scope ids must come from active context and never be solicited from the user, and free-text course codes/school names belong in the query. It stops short of describing result shape or pagination.

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, zero filler, and the primary invocation rule (query alone) is front-loaded before the optional-parameter caveats and the sibling exclusion. Every clause carries actionable instruction.

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 search tool with no output schema and fully described parameters, the description covers selection, invocation, and parameter routing adequately. The only gap is what the results contain or how many/pagination, which is minor given limit is documented in the 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 the baseline is 3, but the description adds routing semantics the schema only partly encodes: that course codes and school names the user typed go into query rather than the UUID parameters, and that schoolId/courseId are pre-existing context values, not user-facing inputs. This materially reduces the chance of the agent misassigning a value to the wrong parameter.

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 ('Search the public uNotes document library') plus the searchable fields (title, course, type keywords). It also draws a hard boundary against sibling listing tools ('not for the user's own quizzes or flashcards'), so an agent can separate it from list_my_quizzes/list_my_flashcards without reading schemas.

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 prescribes the invocation pattern ('Call it with the query alone whenever no scope id is already known'), labels schoolId/courseId as optional narrowing hints that are 'never prerequisites', and forbids asking the user for them. It also names the alternatives (the user's own listing tools) for the excluded case.

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