Studocu

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

Annotations declare a non-read-only, non-destructive write, and the description adds genuinely new behavioral context beyond them: partial success semantics ('Returns the sources that were successfully added') and a reconciliation step against document_ids. It doesn't cover auth/permission needs, but the partial-failure disclosure is the highest-value trait for this operation.

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, no filler. The action and its limit are front-loaded, and the second sentence carries the one non-obvious detail (partial add results).

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 two-parameter write with full schema coverage, annotations covering the safety profile, and an output schema handling return structure, the description is essentially complete. The partial-success note is the key gap-filler; only minor behavioral detail (e.g., duplicate handling) is absent.

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 both parameters are already documented with UUID format and the 1–10 item bounds. The description's 'up to 10' and 'from search-documents' largely restate what the schema's maxItems and descriptions already say, so 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?

States a specific verb (attach), resource (Studocu documents), source tool (search-documents), destination (a project), and a hard scope limit (up to 10). An agent can distinguish this from siblings like search-documents or create-project without opening any schema.

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 mention of 'from search-documents' implicitly establishes the prerequisite workflow — search first, then attach the resulting IDs. It gives clear usage context but names no explicit exclusion or alternative path, so it stops short of a full when/when-not statement.

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, openWorldHint=false and destructiveHint=false, so the safety profile is covered. The description adds that this is a no-side-effect verification/proof call, which is useful, but it doesn't describe outcomes on success vs. invalid session. With annotations carrying the safety burden, 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?

A single front-loaded sentence with no filler, starting with the imperative 'Use this...'. Efficient, though it leans on internal jargon rather than plain language.

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 verification tool with complete annotations and an output schema (which carries return values), the description covers what the call confirms. The only minor gap is expected behavior when the session is invalid, which the output schema plausibly covers.

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 takes zero parameters and schema coverage is 100%, so per the rubric the baseline is 4. The description adds nothing about parameters because there are none to describe.

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 ('verify') and resource ('Agent OS MCP server received a valid delegated Studocu session'), so an agent knows this confirms server-side session validity. It is clearly distinct from the memory/project/document siblings, though the jargon 'proof tool' is a bit opaque.

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?

'Use this proof tool to verify...' implies the context for invoking it, but gives no conditions, prerequisites, or mention of alternatives. Usage is implied rather than spelled out.

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=false, destructiveHint=false, openWorldHint=false, so the safety profile is covered structurally. The description adds one genuine behavioral detail beyond them: course_id is validated before creation, implying a possible pre-write failure. It says nothing about permissions, side effects of creating a project, or what happens when validation fails.

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, front-loaded with the action and followed by the validation caveat. Nothing is padded, though the second sentence is slightly narrow given other behavioral gaps it could have covered instead.

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?

An output schema exists, so return values need not be explained. However, for a mutation tool whose parameters are all optional, the description omits what a 'Studocu project' entails, what a validated-but-invalid course_id does, and how it relates to update-project/get-project-state in the workflow.

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 carries the full burden for three parameters. It names emoji and course (course_id) and notes course_id must be numeric and is validated, but the title parameter and its constraints (non-blank, 255-char max) are never mentioned, leaving a third of the surface undocumented in both places.

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+resource ('Create a Studocu project') plus the optional configurable fields, so the agent knows exactly what the tool produces. It does not differentiate itself from the sibling update-project, which is the obvious near-neighbor an agent could confuse it 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?

There is no guidance on when to use this versus update-project, no statement that all parameters are optional (creation can succeed with an empty body), and no prerequisites or preconditions. 'Optionally configure' hints at optionality but is not actionable 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?

Annotations already declare destructiveHint=true and readOnlyHint=false, so the safety profile is covered. The description adds genuinely new behavior context beyond them: deletion is limited to a single document, and the acting identity comes from the session bearer rather than from input. It still omits idempotency/not-found behavior, so it stops at 4.

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 short sentences, front-loaded with the action, then scope selection, then the identity note. No filler and nothing repeated for padding.

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?

An output schema exists, so return values need no explanation, and annotations carry the destructiveness signal. The description covers scope, identity, and granularity adequately; only failure/idempotency behavior is unaddressed for what is an irreversible mutation.

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 both parameters are already documented by the schema, and the description's project_id explanation largely restates it. The only incremental value is the framing of (scope, kind) as the composite identity key. Baseline 3 is 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 gives a specific verb ("Delete") and a precisely scoped resource ("one durable memory document identified by (scope, kind)"). An agent can instantly place it against read-memory and write-memory. It stops short of naming those siblings explicitly, which is the only gap.

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 states the condition for each scope choice ("Provide project_id for project-local memory, or null/omit for global"), which is useful routing guidance. However, there is no when-to-use/when-not guidance relative to siblings, no warning about irreversibility, and no note on what happens if the document does not exist.

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/destructiveHint annotations, it discloses non-obvious behavior: topic_masteries is conditionally omitted when detail was not loaded, empty means loaded-but-no-practised-topics, and mastery appears only on projects, not followed_courses. It also states the read-only contract and the source-of-truth model (Infinite Practice attempts write; Agent OS only reads), which an agent cannot infer from 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?

Front-loads the purpose and payload before getting into conditional field semantics, and most sentences carry operational weight. It is dense at roughly 150 words with some tangential material (the ACE/mobile/write-path aside), but nothing is outright filler for a tool with this much conditional output.

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?

Although an output schema exists, the description supplies the interpretive layer the schema can't: the omitted-vs-empty distinction for topic_masteries and where mastery flags live. Combined with the read-only statement and scope semantics, an agent has everything needed to call and interpret 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 coverage is 100%, so baseline is 3, but the description adds real meaning: it explains that course_id/project_id narrow which course is 'in scope' and therefore whether topic_masteries is populated. That causal link between the scoping parameters and the conditional output field goes beyond the schema's terse 'Narrow context to...' text.

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 ('Return the unified Agent OS context manifest for the authenticated user') and enumerates the payload: profile, followed courses, project metadata, recent activity. It also draws a boundary against siblings by naming get-course-mastery as the tool for practised-topic detail, so the agent can separate them without opening either schema.

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 an explicit alternative and the condition selecting it: 'Use get-course-mastery(course_id) for the practised-topic list when context omitted detail.' It also explains when topic detail is in scope (project_id, sole remaining project, or shared course_id). What's missing is any routing guidance versus get-project-state or agent-os-session, so it stops short of full when/when-not coverage.

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 read-only, but the description adds substantive context they cannot: the source of truth (user_topic_mastery keyed by identity+course+topic), the scoping model (learner/course-scoped, not chat/client-scoped), who writes vs reads the rows, and the meaning of an empty result ('no IP attempts yet, not a separate client score').

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?

Front-loads the purpose and return shape before the routing and scoping notes, which is the right order. It runs a bit long, with two adjacent sentences covering overlapping read-only/scoping claims, but nothing is truly wasted.

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-param read tool with an output schema present, the description covers everything an agent needs: when to call it, what the fields mean, the empty-state interpretation, and the scoping/data-origin model. Nothing material 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% for the single course_id parameter and the schema already documents it fully as a positive course id. The description only restates 'Requires course_id', adding no syntax, format, or constraint detail beyond the structured field, so 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?

Opens with a specific verb+resource ('Return practised-topic Infinite Practice mastery for a course') and enumerates exactly what comes back (topic_id, topic_name, display 0–100, questions_answered). It is clearly separable from neighbors like get-context and get-course-syllabus.

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?

States a concrete trigger: 'Use after get-context flags (has_course_mastery / started_course_mastery) or whenever context omitted topic_masteries.' This names the related tool and the condition that selects it, though the inverse case (skip it when get-context already supplied masteries) is only implied rather than stated.

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 cover the safety profile (readOnlyHint, destructiveHint=false, closed-world), so the bar is lower. The description adds real behavioral context beyond them: the syllabus is a generated artifact that may not exist for every course ("when this tool has one"), and the payload is markdown. It stops short of saying what happens when no syllabus exists.

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 short sentences, front-loaded with the action and return format, followed by value framing and the required parameter. No filler; every sentence earns its place.

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, return-value detail is not the description's burden, and the single parameter plus annotations are covered. The only gap is the failure mode when a course has no generated syllabus, which the conditional phrasing hints at but never resolves.

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 course_id param is fully documented there, so the baseline is 3. "Requires course_id" merely restates the schema's required field without adding format, range, or sourcing detail.

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 (return a generated course outline) plus the format (markdown), which clearly separates it from siblings like read-artifact or get-course-mastery. It does not name an alternative sibling, but the resource is specific enough for an agent to identify the right 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?

"This is the best grounding for high-quality study guidance" implies a usage context (study/learning tasks) but never states when not to use it or which sibling to prefer for adjacent needs. Usage is inferable 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?

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is free. The description adds genuine context beyond that: the external_id matching trick for correlating a request-creation with a creation once 'Alpha identity appears', and the access-scoped result set. It stops short of noting the 20-id batch cap or pagination behavior.

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 front-loaded sentences with no filler: purpose, the non-obvious matching nuance, then the sequencing rule. The middle sentence is densely jargon-laden ('external_id', 'Alpha identity'), but it carries real information rather than padding.

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?

An output schema exists, so return structure is covered elsewhere, and annotations carry the safety profile. The description covers purpose, ordering, access scoping, and id-correlation semantics; only minor operational details (batch limit, empty/missing-id behavior) are left to 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 description coverage is 100% and the single 'ids' parameter is already documented in the schema with essentially the same wording the description reuses. The description adds no format, ordering, or batching detail (e.g. the maxItems of 20) beyond what the schema provides, 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?

States a specific verb and resource ('Return sources and creations (project state)') plus the scope ('for one or more projects by id'). It explicitly differentiates from the closest sibling by noting that get-context 'lists projects without their sources/creations', so an agent can pick between them without opening either schema.

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 prerequisite and ordering ('Use after get-context ... to load those projects' artifacts'), which is precisely the condition that selects this tool over the alternative. The access caveat ('Only projects you can access are returned') further constrains when it is useful.

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, openWorldHint=false and destructiveHint=false, so the safety profile is covered. The description adds that it returns normalized metadata with inline content, a small behavioral detail, but says nothing about pagination behavior despite accepting a cursor.

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 tight sentences with the identifying URI format front-loaded and no filler. Sizing is appropriate for the tool's simplicity, though the second sentence is somewhat redundant given an output schema exists.

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 annotations covering safety, the description need not explain return values. It still conveys the identifier form and purpose adequately; only the cursor/pagination behavior is left unaddressed.

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 both parameters are documented in the schema itself. The description restates the URI format but adds no meaning beyond what the schema already provides, making the baseline 3 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?

States a specific verb (Read) and resource (a Studocu project source or creation), plus the exact URI form that identifies it. This is clear, but it doesn't name a sibling (e.g. read-detached-document or write-artifact are not clearly contrasted), so it misses full 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 URI-based framing implies when the tool applies, but there is no explicit when-to-use/when-not guidance and no reference to alternatives like read-detached-document or read-web-url. Usage context is only inferable.

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, destructiveHint=false, and openWorldHint=false, so the safety profile is covered; the description adds the non-obvious side-effect guarantee that no project source is created, which is meaningful beyond readOnly. It does not cover document size limits, pagination, or failure modes, so it stops short of a 5.

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, no filler, with the core capability and its scope constraint front-loaded ahead of the sibling reference. Every sentence earns its place by disambiguating from read-artifact.

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 tool with full annotation coverage and an output schema, nothing essential is missing: the agent knows what it reads, that it won't mutate project state, and which sibling to use instead. Return values are already handled by the output 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?

Only one parameter and schema description coverage is 100%, so the schema fully documents document_id, including its positive-integer bound. The description's only parameter-adjacent signal ('without creating a project source') restates the same concept, adding no syntax or format detail beyond the schema. Baseline 3 for a schema-does-the-work case.

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 (read) and resource (a Studocu document) plus the defining scope condition: no project source required or created. It explicitly separates itself from the sibling read-artifact, so an agent can choose between them without opening either schema.

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 the selecting condition directly ('without requiring or creating a project source') and names the alternative tool with its own condition ('Use read-artifact for documents attached to a project'). This is an explicit when/when-other routing rule, not implied 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?

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds genuinely useful behavioral context beyond that: the identity/auth model (session bearer, not input) and the return shape ('one document per (scope, kind)').

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 tight sentences, no filler, with the core action front-loaded and the scoping/auth caveats following. Every sentence carries distinct 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?

An output schema exists, so return values need not be explained in prose. Combined with full schema coverage and read-only annotations, the description covers what an agent needs, though a brief routing note against sibling read tools would make it fully complete.

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 every parameter is already documented in the schema, including the scope default rule and the project_id requirement. The single mention of project_id in the description duplicates schema content rather than adding new meaning, so 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?

Clear specific verb+resource: 'Read durable agent memory for the authenticated user.' The read/write/delete-memory triplet is self-distinguishing, so an agent can tell it apart from write-memory and delete-memory without much inference, though the description never names those siblings 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 description gives no when-to-use guidance or exclusions relative to siblings like get-context or read-artifact. 'Use project_id for project-scoped memory' is parameter steering, not usage guidance. The agent is left to infer when this tool is the right call.

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 cover the safety profile (readOnlyHint, destructiveHint=false, openWorldHint), so the bar is lower. The description adds real value beyond them: the tool returns grounded page content, requires a public URL, and rejects competitor study-material hosts. It stops short of describing failure behavior (timeouts, paywalls, non-public URLs) or rate limits.

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 tight sentences, with the core action front-loaded and the routing constraints immediately after. There is mild duplication of the sibling-routing guidance that also appears in the url parameter description, which keeps it just under a top score.

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?

An output schema exists, so return-value detail is unnecessary, and the annotations carry the read-only/open-world profile. The description covers the URL prerequisite and host restrictions; only edge-case behavior on failed or blocked reads is left unaddressed.

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% for both parameters, so the schema already documents url and the optional query extraction instruction. The description adds no syntax, format, or length guidance beyond that, making 3 the correct baseline.

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 ('Read a specific public URL') plus the output intent ('return grounded page content for agent evidence'), and names the siblings it is not (search-documents, search-web). An agent can distinguish it from the search tools without opening any schema.

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 routing: use this when you already have the exact URL; use search-documents for Studocu documents; use search-web for open-web discovery. It also states an exclusion ('Competitor study-material hosts are rejected'), which is exactly the when-not guidance that prevents wasted calls.

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 the write/non-destructive profile; the description goes well beyond by disclosing the ~3-minute wait, the three distinct outcome shapes (created, creating, outcome_unknown), the duplicate/in-flight case, and idempotency-key forwarding and dedupe semantics. This is exactly the latency and failure-mode context an agent needs before invoking a long-running generator.

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 purpose, and every clause carries operative information (latency, outcome states, retry path, idempotency). The second sentence is dense and semicolon-heavy, which slightly taxes parsing, but there is 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?

With an output schema present, the description need not enumerate return fields, yet it usefully summarizes the possible states and the retry escape hatch. Combined with the latency bound and idempotency rules, an agent has everything needed to call this safely on the first attempt.

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; the description adds real meaning by stating that artifact_ids must be 1-10 project source artifacts and that idempotency_key is forwarded as Idempotency-Key and that identical retries dedupe even without a key. It does not restate the type enum or project_id semantics, but it enriches the two parameters that most affect behavior.

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 (Generate) and resource (Studocu quiz or mockExam) plus the input scope (1-10 project source artifacts). It is readily distinguishable from the closest sibling create-project and from get-project-state, which it names explicitly in the retry path.

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 recovery instruction: on outcome_unknown (timeout or in-flight duplicate), check get-project-state before retrying, and notes that retries without a key still dedupe. It lacks any explicit when-to-use framing versus the other creation/write tools, but the guidance it does give is actionable.

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/openWorld=false/non-destructive, yet the description adds substantial behavior beyond them: what results contain, that institution_name is present only 'when Algolia has it,' an auto-pick rule with an ambiguity fallback, and conversation-scoped ID lifetime. This is rich operational context an agent could not infer from structured fields.

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?

Front-loaded purpose followed by scoping, result shape, and interaction rules; each sentence carries distinct guidance. It is dense but slightly overlong, with the user-presentation rule sitting as a somewhat separate concern.

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?

Covers scoping, fallback behavior, disambiguation, and lifecycle for a tool where the output schema already documents return shape. The only real gap is the undocumented limit parameter, so it is near-complete rather than fully so.

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 carry parameter meaning. It does so well for institution_id (where to source it, and the richer result fields when omitted), but leaves limit (default 3, max 10) and query length constraints entirely undocumented. Partial compensation warrants a 3.

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 definition opens with a specific verb+resource ('Search Studocu courses') and anchors it to a concrete use case ('when establishing or correcting course context'). It is easily distinguished from siblings like search-institutions and search-documents, which are referenced for their distinct roles.

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 and when-not guidance: 'Prefer institution_id from search-institutions to scope results. Omit institution_id only when the institution is unknown' plus 'Do not require this before every document search.' It names the alternative tool and the exact condition that selects 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=true/openWorldHint=false/destructiveHint=false, so safety is covered. The description adds genuine behavioral context beyond that: precedence of course_id over course, that institution is display-name-only with no institution_id, and that the returned institution is the pinned course's university rather than the name passed. It does not cover pagination or ranking behavior, so it is not fully exhaustive.

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?

Front-loaded with the use case before the filter mechanics, and nearly every sentence carries actionable constraint. It is dense and repeats the course_id-wins rule twice, which costs it a point, but there is little outright 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?

With an output schema present, return values need no explanation, and the description nonetheless sketches them (titles, course/institution, ratings, links). Filter precedence, argument-source guidance, and the sibling escape hatch are all present, so an agent has everything needed to call this 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 the baseline is 3 and much of the field guidance (query-is-keywords-only, course_id overrules course) is already mirrored in the schema. The description still adds cross-tool guidance — prefer numeric course_id sourced from search-courses — and consolidates the precedence rules in one place, which is meaningful for argument construction.

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 specific verbs (find, search, browse) and a concrete resource (study documents, lecture notes, summaries, course materials on Studocu). It also names the sibling it is not (search-web for open-web sources), so an agent can separate this from the other search tools without opening a schema.

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, explicit when-not (open-web sources → search-web), and explicit filter-precedence conditions (course_id overrules course; course is optional extra; omit unknown filters). Alternative tool and selecting conditions are named rather than 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 cover the safety profile (readOnly, non-destructive, closed-world), and the description layers on genuinely new behavior: the disambiguation policy (auto-pick a clear top match, ask the user when ambiguous), the user-facing presentation rule (show name/type/country/region, never internal IDs), and the ID lifecycle ('conversation-scoped until a persistence capability owns them'). None of that is 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?

Front-loads purpose and the usage gate in the first two sentences, then adds policy. It is dense but every sentence carries a distinct instruction; the ID/presentation guidance is slightly beyond tool-invocation scope but still actionable.

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, the description need not enumerate return fields, though it helpfully does. The usage gate and disambiguation policy make the tool callable correctly; the only real hole is the unexplained 'type' and 'limit' parameters.

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 carries the full burden, yet it only clarifies the 'query' parameter implicitly ('by name'). The 'type' enum (UNIVERSITY / HIGH_SCHOOL) and the 'limit' parameter (default 3, max 10) are never mentioned, so an agent gets no guidance on filtering by institution type or controlling shortlist size.

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 Studocu institutions by name') plus the scope constraint that names are the lookup key. This is clearly distinguishable from sibling search tools such as search-courses and search-documents, which search 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 names the triggering context ('when establishing or correcting education context (onboarding / context setup)') and an exclusion ('Do not require this before every document search'). That is both a when-to-use and a when-not-to-use instruction, which is rare and valuable.

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 (readOnlyHint, openWorldHint, destructiveHint=false), and the description adds non-obvious behavior: results are grounded with citation URLs and competitor study-material domains are filtered out. It does not discuss rate limits or latency, and the return format is covered by the output schema, so a 4 is fair.

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 tight sentences, zero filler. The core capability is front-loaded, followed by the routing exclusion and the domain-filtering caveat.

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?

Return values are covered by the output schema, safety by annotations, and parameters by a fully covered schema, so the description's remaining job is routing and exclusion behavior — both handled explicitly. Nothing an agent needs to select or invoke this tool correctly 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%, so both parameters are already documented in the schema, including the 'site' domain-filter example. The description adds no syntax or format detail beyond what the schema provides; the query guidance merely echoes the routing rule. Baseline 3 applies when the schema does the heavy lifting.

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 ('Answer open-web questions with a grounded response and citation URLs') and explicitly scopes it to non-Studocu sources. An agent can distinguish it from search-documents without opening either schema.

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 routing rule: use this tool for open-web questions, and use search-documents for Studocu study documents, lecture notes, summaries, or course materials. It also warns that competitor study-material domains are excluded, so the agent knows when results will be absent rather than assuming failure.

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=false, destructiveHint=false, openWorldHint=false, so the safety profile is covered. The description adds genuine behavioral context beyond the schema by disclosing that nulling course_id also clears the institution, an important side effect not visible in the parameter type.

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 filler, with the core operation front-loaded and the tricky clearing rule immediately after it.

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?

An output schema exists, so return values need no explanation, and the non-destructive annotations frame the mutation. The one gap is that the anyOf constraint (at least one of title/emoji/course_id) is only implied rather than stated.

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 25%, so the description must carry the load; it names and explains the three mutable fields and, crucially, defines the null semantics for course_id. It does not explain the schema's anyOf/minProperties=2 requirement that at least one field be supplied, nor project_id beyond its required status.

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 ('Update') plus the resource ('Studocu project') and the three updatable fields (title, emoji, course). It is clearly distinguishable from the sibling create-project by the mutation verb, though it never names the sibling 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 only operational guidance is the course_id=null clearing rule, which is really a parameter note. There is no statement of when to use this versus create-project or get-project-state, and no prerequisites are given, so usage is only implied.

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=false, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds that the artifact type dictates the content shape, which is useful framing, but it discloses no additional behavioral traits like permissions, side effects, or limits. 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?

Two short sentences, front-loaded with the action and followed by the required inputs. Every clause earns its place 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 polymorphic write tool supporting five artifact types, the description never names or distinguishes the supported types, leaving that discovery entirely to the schema. An output schema exists so return values need no explanation, but the type-level guidance is a real gap given the complexity.

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 schema fully documents project_id and the artifact envelope. The description restates the two inputs at a high level but adds no syntax or type-specific detail beyond what the schema already provides, making the baseline 3 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?

States a specific verb and resource ('Create a Studocu artifact from typed content') and clarifies the input contract ('project_id and an artifact envelope; the artifact type defines the required content shape'). It is clear but does not explicitly differentiate itself from siblings like read-artifact or request-creation.

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 on when to use this tool versus alternatives such as request-creation or read-artifact, and no prerequisites or exclusions are stated. Usage must be inferred entirely from the name.

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 destructiveHint=true and openWorldHint=false, so the safety profile is covered. The description adds real context beyond that: the upsert is keyed one-document-per-(scope, kind) (implying replacement of prior content) and identity is derived from the session bearer rather than input. It does not explicitly state that existing content is overwritten or what errors occur.

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, zero waste, with the core upsert/keying semantics front-loaded before the scope-selection detail. Every clause earns its place.

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?

An output schema exists, so return values need not be explained, and the description covers scope, keying, and auth identity for a mutation tool. It leaves out what happens to previously stored content on overwrite and whether 'kind' is an open or constrained vocabulary, which keeps it from a 5.

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 kind, value, and project_id are already fully documented in the schema; the description largely restates the project_id null/omit behavior. The one added nuance is that identity is not a parameter but comes from the session bearer. Baseline 3 is 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?

States a specific verb (upsert) and resource (durable memory document) with the keying semantics '(scope, kind) per authenticated user', which distinguishes it from read-memory and delete-memory. It does not explicitly name a sibling or say what it is not, so it stops short of a 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?

Gives a clear condition for choosing project-local vs global storage via project_id, which is genuine usage guidance. However, it never says when to prefer this tool over siblings like write-artifact or get-context, and gives no prerequisites or exclusion cases, so guidance 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.